Endpoints, authentication, limits and response formats. Plans and API keys: see Developers. Machine-readable spec: /openapi.json.
post/api/v1/check
Check up to 5,000 tracks
Send rows as JSON or CSV. Each row counts as one track against your monthly quota. Unknown columns are ignored; missing columns are treated as empty.
Body: application/json or text/csv
get/api/v1/usage
Current month's usage for your key
Finding object
| row | integer | 1-based row number in your input |
| rule | string | |
| severity | error | warning | info | |
| status | string | documented = stated in a published guideline; heuristic = a pattern we flag for review |
| field | string | |
| value | string | |
| message | string | |
| suggestion | string | null | |
| sources | string[] |
Full machine-readable spec: /openapi.json (OpenAPI 3.1.0). Import it into Postman, Insomnia or a client generator.
| Authentication | Authorization: Bearer msg_live_… (or X-API-Key). Keys are issued per account and stored only as a hash. We can't recover a lost key, but we can revoke it and issue a new one. |
|---|---|
| Rate limit | Per key, per minute (60 on Starter, 300 on Growth). Over the limit you get 429 with code rate_limited and a Retry-After header. |
| Monthly quota | Counted in tracks (rows checked), reset on the 1st of each month (UTC). A request that would exceed the quota is rejected whole with 429 quota_exceeded and isn't counted. |
| Request size | Up to 5,000 rows and 5 MB per request. |
| Headers | Every successful response includes X-RateLimit-Limit, X-Quota-Limit and X-Quota-Remaining. |
| Data | Request bodies are processed in memory and not stored. We keep per-key monthly counts of requests and tracks. |
Send rows as JSON or a CSV file with the columns artist, featured_artists, track_title, version, release_title, genre, explicit, isrc, upc, language, ai_use, duration. Every row comes back with its findings, a suggested fix and the published guideline behind it.
curl https://metadatastyleguidelines.pages.dev/api/v1/check \
-H "Authorization: Bearer $MSG_API_KEY" \
-H "Content-Type: application/json" \
-d '{"rows":[{"artist":"Nova Reyes","track_title":"Golden Hour ft. Kai Lane",
"isrc":"US-RC1-26-00002","upc":"036000291452","explicit":"false",
"genre":"Pop","language":"en","ai_use":"None","duration":"3:05"}]}'curl https://metadatastyleguidelines.pages.dev/api/v1/check \ -H "Authorization: Bearer $MSG_API_KEY" \ -H "Content-Type: text/csv" \ --data-binary @release.csv
Response (abridged)
{
"rows": 1,
"counts": { "error": 1, "warning": 1, "info": 0 },
"findings": [
{ "row": 1, "rule": "ISRC_FORMAT", "severity": "error", "status": "documented",
"field": "isrc", "value": "US-RC1-26-00002",
"message": "Deliver without hyphens/spaces/lowercase",
"suggestion": "USRC12600002",
"sources": ["https://isrc.ifpi.org/en/isrc-standard/code-syntax", "…"] },
…
],
"usage": { "month": "2026-10", "tracks_used": 1, "tracks_limit": 10000 }
}