# Clean Songs
> Analyze customer-provided text in Portuguese and English for profanity, drugs, violence, and explicit sexual content. Get clear classifications, minimal evidence, and line numbers using deterministic rules.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/clean-songs/..."
```

## Pricing
- **Free** (Free) — 1,000 calls/Mo, 1 req/s

## Endpoints

### v1

#### `GET /v1/health` — Health

Check service availability.

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/clean-songs/v1/health"
```

**Response:**
```json
{
    "status": "ok"
}
```

#### `GET /v1/lyric-submissions/{submission_id}` — Check lyric submission status

Returns only the submission ID and curation status (pending, approved or rejected). Approved lyrics go to an internal archive and are still not displayed to app users. Requires the X-Submission-Token header with the one-time token returned at creation.

**Parameters:**
- `submission_id` (path, required, string) — submission ID to consult curation status
- `X-Submission-Token` (header, required, string) — One-time tracking token returned as tracking_token in the 202 response of POST /v1/lyric-submissions. Send it exactly as received (43 characters). It does not expire and cannot be recovered.

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/clean-songs/v1/lyric-submissions/{submission_id}"
```

#### `GET /v1/reports/{report_id}` — Reports

Returns only the report ID and administrative review status (pending, approved or rejected). Approved means the report was accepted; it does not publish a rule change. Requires the X-Report-Token header with the one-time tracking token returned when the report was created.

**Parameters:**
- `X-Report-Token` (header, required, string) — One-time tracking token returned as tracking_token in the 202 response of POST /v1/reports. Send it exactly as received (43 characters: letters, digits, "-" and "_"). Keep it secret; it cannot be recovered or reissued. Never put it in the URL or query string.
- `report_id` (path, required, string) — Report ID returned as report_id in the 202 response of POST /v1/reports (32 lowercase hexadecimal characters). Knowing the ID alone does not grant access; the matching X-Report-Token header is also required.

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/clean-songs/v1/reports/{report_id}"
```

#### `POST /v1/analyze-text` — Analyze Text

Analyze customer-provided text in Portuguese or English.

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/clean-songs/v1/analyze-text"
```

#### `POST /v1/lyric-submissions` — Submit lyrics for curation

	
Submit complete lyrics with song title and artist for human curation. Requires rights_confirmed and consent_to_store set to true. Submitted lyrics are never displayed to app users. Returns a submission ID and a one-time tracking token.

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/clean-songs/v1/lyric-submissions"
```

#### `POST /v1/reports` — Report an analysis issue

Submit a false-positive or false-negative report for human review. Includes optional evidence of up to 280 characters and requires explicit consent to store the report. Reports do not automatically change detection rules.

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/clean-songs/v1/reports"
```


---
Marketplace page: https://www.oanor.com/api/clean-songs
OpenAPI spec: https://www.oanor.com/api/clean-songs/openapi.json