{"openapi":"3.1.0","info":{"title":"MatchTune Audit API","description":"Submit social-media posts (YouTube, TikTok, Instagram, Facebook) and get back, per post, what music it uses,\nwhether that music is in your licensed libraries, and a compliance verdict.\n\n**Authenticate** every call with your API key, either as `X-API-Key: <key>` or `Authorization: Bearer <key>`.\nEverything you create is scoped to your account: other accounts' requests are invisible (404), never forbidden (403).\n\n**Carousels.** An Instagram carousel holding several videos is audited one item per video: the extra items are added\nto the request as it runs (they carry `parent_job_id`), so `total_items` can grow after submission. Each slide's result\ngives its own `POST URL` and the carousel as `PARENT POST URL`.\n\n**Flow.** `POST /v1/requests` with your posts → one `job_id` per item → poll `GET /v1/requests/{id}` or\n`GET /v1/requests/{id}/results`, or give a `callback_url` and receive a signed webhook per item and one when the\nrequest completes. Your own ids (`external_request_id`, `external_id`) are echoed everywhere so you never have to\nstore ours.\n\n**Errors** always look the same: `{\"error\": {\"code\": \"NOT_FOUND\", \"message\": \"…\", \"trace_id\": \"…\"}}`. Quote the\n`trace_id` (also in the `X-Trace-Id` response header) when contacting support.\n\n**Rate limits.** Accounts may carry a daily item quota; exceeding it returns 429 with code `RATE_LIMITED`.\n","contact":{"name":"MatchTune support","email":"support@matchtune.com"},"version":"1.0.0"},"servers":[{"url":"https://audit-api.matchtune.com","description":"Production"}],"paths":{"/v1/requests":{"post":{"tags":["requests"],"summary":"Submit posts to audit","description":"Creates a request and starts auditing every item. The response lists one job_id per item in submission order; poll the request, list its results, or receive webhooks at callback_url. Send an `Idempotency-Key` header to make a retry return the original request instead of a new one.","operationId":"create_request_v1_requests_post","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"description":"Any unique string per submission; a repeat returns the first request (reused=true).","title":"Idempotency-Key"},"description":"Any unique string per submission; a repeat returns the first request (reused=true)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRequestIn"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRequestOut"}}}},"401":{"description":"Missing, unknown or disabled API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The key is valid but may not do this","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such request or item for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The item has no result yet, or the request conflicts with an earlier one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error: unknown project_code, unknown library, bad url or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Daily limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected error; quote the trace_id to support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"A dependency is not ready (for example the library dictionary is not cached yet)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"callbacks":{"webhook":{"{$request.body#/callback_url}":{"post":{"summary":"Webhook delivery","description":"Sent for item.completed, item.failed and request.completed. Signed with `X-MatchTune-Signature: t=<unix>,v1=<hmac-sha256>` (see Callbacks in the guide). Reply 2xx within 10 s; otherwise we retry after 1 s, 5 s and 25 s.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"2XX":{"description":"Received"}}}}}}},"get":{"tags":["requests"],"summary":"List your requests","description":"Newest first, keyset-paginated: pass `next_cursor` back as `cursor` until it is null.","operationId":"list_requests_v1_requests_get","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/Status"},{"type":"null"}],"description":"Only requests in this status.","title":"Status"},"description":"Only requests in this status."},{"name":"external_request_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Only the request(s) you submitted with this id.","title":"External Request Id"},"description":"Only the request(s) you submitted with this id."},{"name":"project_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Project Code"}},{"name":"created_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"ISO 8601; only requests created after this instant.","title":"Created After"},"description":"ISO 8601; only requests created after this instant."},{"name":"created_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"ISO 8601; only requests created before this instant.","title":"Created Before"},"description":"ISO 8601; only requests created before this instant."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque, from a previous page's next_cursor.","title":"Cursor"},"description":"Opaque, from a previous page's next_cursor."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"customer_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Operator keys only; ignored for API keys.","title":"Customer Id"},"description":"Operator keys only; ignored for API keys."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestsPage"}}}},"401":{"description":"Missing, unknown or disabled API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The key is valid but may not do this","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such request or item for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The item has no result yet, or the request conflicts with an earlier one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error: unknown project_code, unknown library, bad url or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Daily limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected error; quote the trace_id to support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"A dependency is not ready (for example the library dictionary is not cached yet)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/requests/{request_id}":{"get":{"tags":["requests"],"summary":"Request progress","description":"Counts per status and per step, throughput, an ETA once enough items completed, and the libraries in scope.","operationId":"get_request_v1_requests__request_id__get","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Request Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicRequestDetail"}}}},"401":{"description":"Missing, unknown or disabled API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The key is valid but may not do this","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such request or item for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The item has no result yet, or the request conflicts with an earlier one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error: unknown project_code, unknown library, bad url or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Daily limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected error; quote the trace_id to support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"A dependency is not ready (for example the library dictionary is not cached yet)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/requests/{request_id}/items":{"get":{"tags":["requests"],"summary":"List a request's items","description":"In submission order. `cursor` is the position to start from (from the previous page's next_cursor).","operationId":"list_items_v1_requests__request_id__items_get","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Request Id"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/Status"},{"type":"null"}],"description":"Only items in this status.","title":"Status"},"description":"Only items in this status."},{"name":"stage","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only items currently in this step: DOWNLOAD, PROCESSING, ENRICHMENT or COMPLETE.","title":"Stage"},"description":"Only items currently in this step: DOWNLOAD, PROCESSING, ENRICHMENT or COMPLETE."},{"name":"external_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Only the item(s) submitted with this external_id.","title":"External Id"},"description":"Only the item(s) submitted with this external_id."},{"name":"cursor","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Cursor"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemsPage"}}}},"401":{"description":"Missing, unknown or disabled API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The key is valid but may not do this","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such request or item for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The item has no result yet, or the request conflicts with an earlier one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error: unknown project_code, unknown library, bad url or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Daily limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected error; quote the trace_id to support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"A dependency is not ready (for example the library dictionary is not cached yet)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/requests/{request_id}/results":{"get":{"tags":["requests"],"summary":"List a request's results","description":"Every item of the request in submission order with its audit row (null until the item completes).","operationId":"list_results_v1_requests__request_id__results_get","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Request Id"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Cursor"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/Status"},{"type":"null"}],"description":"Only items in this status.","title":"Status"},"description":"Only items in this status."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResultsPage"}}}},"401":{"description":"Missing, unknown or disabled API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The key is valid but may not do this","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such request or item for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The item has no result yet, or the request conflicts with an earlier one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error: unknown project_code, unknown library, bad url or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Daily limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected error; quote the trace_id to support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"A dependency is not ready (for example the library dictionary is not cached yet)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/items/{job_id}":{"get":{"tags":["items"],"summary":"Item progress","description":"The item's status, its current step and the timing of each step.","operationId":"get_item_v1_items__job_id__get","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicItemDetail"}}}},"401":{"description":"Missing, unknown or disabled API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The key is valid but may not do this","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such request or item for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The item has no result yet, or the request conflicts with an earlier one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error: unknown project_code, unknown library, bad url or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Daily limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected error; quote the trace_id to support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"A dependency is not ready (for example the library dictionary is not cached yet)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/items/{job_id}/result":{"get":{"tags":["items"],"summary":"Item result","description":"The audit row of a completed item. 409 with code NOT_READY while the item is still running or failed.","operationId":"get_item_result_v1_items__job_id__result_get","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditResult"}}}},"401":{"description":"Missing, unknown or disabled API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The key is valid but may not do this","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such request or item for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The item has no result yet, or the request conflicts with an earlier one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error: unknown project_code, unknown library, bad url or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Daily limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected error; quote the trace_id to support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"A dependency is not ready (for example the library dictionary is not cached yet)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"AuditResult":{"properties":{"PLATFORM":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Platform"},"POST ORIGIN":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Post Origin","description":"The account that published the post, as a handle."},"TRACKED ACCOUNT":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tracked Account"},"ACCOUNT TYPE":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Type","description":"Owned or Collaboration."},"PARENT POST URL":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Post Url","description":"For a carousel slide, the carousel it belongs to; - otherwise."},"POST URL":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Post Url"},"POST DATE":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Post Date","description":"YYYY-MM-DD HH:MM:SS (date only when the platform gives no time)."},"POST TYPE":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Post Type","description":"Video, Carousel (one slide of a multi-media post) or Image."},"AUDIO STATUS":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Audio Status","description":"Audio Recognized, Audio Not Recognized or No Audio."},"AUDIO CATEGORY":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Audio Category"},"IN TARGET LIBRARY":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"In Target Library","description":"Yes or No for a recognised track, else -."},"MUSIC SOURCE":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Music Source","description":"The MatchTune music source, or Not Found in Target Libraries."},"REVIEW FLAG":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Flag","description":"Review Required, Cross-Platform Use, or -."},"MATCH CONFIDENCE":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Match Confidence","description":"High for a recognised track: the identification is established. Medium when two engines agreed but their agreement rests on one shared source and no fingerprint proof backs it (REVIEW FLAG Review Required). - otherwise. A post whose candidates compete or are too weak to stand alone is reported as not recognised, with no track."},"RISK STATUS":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Risk Status","description":"At Risk, Compliant or Unverified."},"LICENSE END DATE":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"License End Date"},"TRACK NAME":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Track Name","description":"The recording the audio matched. For a re-upload published under an uploader's name, the original recording it reproduces."},"TRACK ARTIST":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Track Artist"},"TRACK RECORD LABEL":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Track Record Label"},"TRACK ISRC":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Track Isrc"},"POST CAPTION":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Post Caption"},"VIDEO DURATION (SEC)":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"null"}],"title":"Video Duration (Sec)"},"MUSIC DURATION (SEC)":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"null"}],"title":"Music Duration (Sec)"},"MUSIC PRESENCE SCORE":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"null"}],"title":"Music Presence Score","description":"0-100."},"POST LIKES":{"anyOf":[{"type":"integer"},{"type":"string"},{"type":"null"}],"title":"Post Likes"},"POST COMMENTS":{"anyOf":[{"type":"integer"},{"type":"string"},{"type":"null"}],"title":"Post Comments"},"ARTIST POPULARITY":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Artist Popularity","description":"Tier 1: Mega Artists … Tier 5: Long-Tail Artists."}},"additionalProperties":true,"type":"object","title":"AuditResult","description":"One audit row. Keys are the spreadsheet's column names; an empty value is \"-\".","example":{"ACCOUNT TYPE":"Owned","ARTIST POPULARITY":"Tier 4: Moderate Reach Artists","AUDIO CATEGORY":"Music Only","AUDIO STATUS":"Audio Recognized","IN TARGET LIBRARY":"No","LICENSE END DATE":"-","MATCH CONFIDENCE":"High","MUSIC DURATION (SEC)":24.8,"MUSIC PRESENCE SCORE":88.6,"MUSIC SOURCE":"Not Found in Target Libraries","PARENT POST URL":"-","PLATFORM":"Instagram","POST CAPTION":"#ad the caption","POST COMMENTS":15,"POST DATE":"2026-05-01 09:12:44","POST LIKES":141,"POST ORIGIN":"example_brand","POST TYPE":"Video","POST URL":"https://www.instagram.com/p/XXXXXXXXXXX/","REVIEW FLAG":"-","RISK STATUS":"At Risk","TRACK ARTIST":"Example Artist","TRACK ISRC":"ZZX012600001","TRACK NAME":"Example Track","TRACK RECORD LABEL":"Example Records","TRACKED ACCOUNT":"example_brand","VIDEO DURATION (SEC)":24.8}},"CreateRequestIn":{"properties":{"items":{"anyOf":[{"items":{"$ref":"#/components/schemas/ItemIn"},"type":"array","minItems":1},{"type":"null"}],"title":"Items","description":"The posts to audit, in order."},"urls":{"anyOf":[{"items":{"anyOf":[{"type":"string"},{"$ref":"#/components/schemas/ItemIn"}]},"type":"array","minItems":1},{"type":"null"}],"title":"Urls","description":"Deprecated: send `items`. Accepted for existing integrations.","deprecated":true},"external_request_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"External Request Id","description":"Your own identifier for this batch; returned on the request and in webhooks."},"callback_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Callback Url","description":"Where to POST webhook events for this request (see Callbacks)."},"project_code":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Project Code","description":"The MatchTune project this request audits for: its scoped libraries and rightsholder flags are applied."},"target_libraries":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":64},{"type":"null"}],"title":"Target Libraries","description":"Without a project_code: the MatchTune library names that count as yours, for example [\"Meta Sound Collection\", \"Epidemic Sound\"]. Omitted: your account's default libraries."},"customer_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Customer Id","description":"Operator keys only. For an API key the customer is the key's account and this field is ignored."}},"type":"object","title":"CreateRequestIn","example":{"external_request_id":"batch-2026-09-22-001","items":[{"external_id":"post-48213","tracked_account":"example_brand","url":"https://www.instagram.com/p/XXXXXXXXXXX/"},{"url":"https://www.tiktok.com/@example_brand/video/1234567890123456789"}],"project_code":"ABC-2607161"}},"CreateRequestOut":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"external_request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Request Id"},"total_items":{"type":"integer","title":"Total Items"},"trace_id":{"type":"string","title":"Trace Id"},"reused":{"type":"boolean","title":"Reused","description":"True when an Idempotency-Key matched an earlier request, which is returned instead.","default":false},"items":{"items":{"$ref":"#/components/schemas/CreatedItem"},"type":"array","title":"Items","description":"One entry per submitted item, in submission order, so each job_id can be tracked at once."}},"type":"object","required":["request_id","total_items","trace_id"],"title":"CreateRequestOut"},"CreatedItem":{"properties":{"job_id":{"type":"string","format":"uuid","title":"Job Id"},"position":{"type":"integer","title":"Position"},"url":{"type":"string","title":"Url"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"},"parent_job_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Job Id","description":"Set on a carousel slide that was split out of another item."}},"type":"object","required":["job_id","position","url"],"title":"CreatedItem"},"DurationStats":{"properties":{"samples":{"type":"integer","title":"Samples"},"avg_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Ms"},"p50_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P50 Ms"},"p95_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P95 Ms"},"p99_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P99 Ms"}},"type":"object","required":["samples","avg_ms","p50_ms","p95_ms","p99_ms"],"title":"DurationStats"},"ErrorBody":{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"trace_id":{"type":"string","title":"Trace Id"},"details":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"null"}],"title":"Details"}},"type":"object","required":["code","message","trace_id"],"title":"ErrorBody"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}},"type":"object","required":["error"],"title":"ErrorResponse"},"ItemIn":{"properties":{"url":{"type":"string","title":"Url","description":"The post to audit: a YouTube, TikTok, Instagram or Facebook url."},"tracked_account":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Tracked Account","description":"The account this post is audited for (TRACKED ACCOUNT). Defaults to the account that published it."},"external_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"External Id","description":"Your own identifier for this post; returned on the item and in webhooks, so you can correlate job_id with it."},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Your own attributes for this post (any JSON object, up to 8 KB), for example a campaign, a market or your internal ids. Stored with the item and returned untouched on the item, with its result and in every webhook for it."}},"type":"object","required":["url"],"title":"ItemIn","example":{"external_id":"post-48213","metadata":{"campaign":"spring-2026","market":"FR"},"tracked_account":"example_brand","url":"https://www.instagram.com/p/XXXXXXXXXXX/"}},"ItemResult":{"properties":{"job_id":{"type":"string","format":"uuid","title":"Job Id"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Your own attributes for this post, exactly as you sent them with the item; returned on the item, with its result and in webhooks."},"parent_job_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Job Id"},"position":{"type":"integer","title":"Position"},"url":{"type":"string","title":"Url"},"status":{"$ref":"#/components/schemas/Status"},"current_stage":{"anyOf":[{"$ref":"#/components/schemas/PublicStage"},{"type":"string"}],"title":"Current Stage"},"last_error":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Last Error"},"result":{"anyOf":[{"$ref":"#/components/schemas/AuditResult"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result","description":"The audit row, null until the item completes."}},"type":"object","required":["job_id","position","url","status","current_stage","last_error","result"],"title":"ItemResult"},"ItemSummary":{"properties":{"job_id":{"type":"string","format":"uuid","title":"Job Id"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Your own attributes for this post, exactly as you sent them with the item; returned on the item, with its result and in webhooks."},"parent_job_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Job Id","description":"For a carousel slide split out of another item: that item. Such items are added to the request while it runs (see Carousels)."},"position":{"type":"integer","title":"Position"},"url":{"type":"string","title":"Url"},"current_stage":{"anyOf":[{"$ref":"#/components/schemas/PublicStage"},{"type":"string"}],"title":"Current Stage","description":"One of the four public steps (operators see internal stages)."},"status":{"$ref":"#/components/schemas/Status"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"last_error":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Last Error"}},"type":"object","required":["job_id","position","url","current_stage","status","created_at","updated_at","last_error"],"title":"ItemSummary"},"ItemsPage":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ItemSummary"},"type":"array","title":"Items"},"next_cursor":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Cursor","description":"The position to pass back as `cursor` for the next page. Null on the last page."}},"type":"object","required":["items","next_cursor"],"title":"ItemsPage"},"PublicItemDetail":{"properties":{"job_id":{"type":"string","format":"uuid","title":"Job Id"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Your own attributes for this post, exactly as you sent them with the item; returned on the item, with its result and in webhooks."},"parent_job_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Job Id","description":"For a carousel slide split out of another item: that item. Such items are added to the request while it runs (see Carousels)."},"position":{"type":"integer","title":"Position"},"url":{"type":"string","title":"Url"},"current_stage":{"anyOf":[{"$ref":"#/components/schemas/PublicStage"},{"type":"string"}],"title":"Current Stage","description":"One of the four public steps (operators see internal stages)."},"status":{"$ref":"#/components/schemas/Status"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"last_error":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Last Error"},"request_id":{"type":"string","format":"uuid","title":"Request Id"},"total_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Ms"},"steps":{"items":{"$ref":"#/components/schemas/PublicStep"},"type":"array","title":"Steps"}},"type":"object","required":["job_id","position","url","current_stage","status","created_at","updated_at","last_error","request_id","total_ms","steps"],"title":"PublicItemDetail","description":"Item as an API user sees it: public steps only, no workers, attempts or storage paths."},"PublicRequestDetail":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"external_request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Request Id"},"customer_id":{"type":"string","title":"Customer Id"},"project_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Code"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"status":{"$ref":"#/components/schemas/Status"},"total_items":{"type":"integer","title":"Total Items","description":"Items in the request; it grows while the request runs when a carousel is split into one item per video."},"counts":{"additionalProperties":{"type":"integer"},"propertyNames":{"$ref":"#/components/schemas/Status"},"type":"object","title":"Counts","description":"Items per status."},"progress_percent":{"type":"number","title":"Progress Percent"},"rate_per_min":{"type":"number","title":"Rate Per Min","description":"Items completed per minute over the last five minutes."},"trace_id":{"type":"string","title":"Trace Id"},"callback_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Callback Url"},"target_libraries":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Target Libraries","description":"The libraries this request was scoped to, resolved to MatchTune's names."},"eta_minutes":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eta Minutes"},"stages":{"additionalProperties":{"additionalProperties":{"type":"integer"},"propertyNames":{"$ref":"#/components/schemas/Status"},"type":"object"},"propertyNames":{"$ref":"#/components/schemas/PublicStage"},"type":"object","title":"Stages","description":"Items per step and status."},"stage_durations":{"additionalProperties":{"$ref":"#/components/schemas/DurationStats"},"propertyNames":{"$ref":"#/components/schemas/PublicStage"},"type":"object","title":"Stage Durations"},"item_durations":{"$ref":"#/components/schemas/DurationStats"}},"type":"object","required":["request_id","customer_id","created_at","status","total_items","counts","progress_percent","rate_per_min","trace_id","callback_url","eta_minutes","stages","stage_durations","item_durations"],"title":"PublicRequestDetail"},"PublicStage":{"type":"string","enum":["DOWNLOAD","PROCESSING","ENRICHMENT","COMPLETE"],"title":"PublicStage","description":"The four steps a customer sees. Internally PROCESSING covers stemize, categorize, identification and merge."},"PublicStep":{"properties":{"stage":{"$ref":"#/components/schemas/PublicStage"},"status":{"$ref":"#/components/schemas/Status"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At"},"duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Ms"}},"type":"object","required":["stage","status","started_at","completed_at","duration_ms"],"title":"PublicStep"},"RequestSummary":{"properties":{"request_id":{"type":"string","format":"uuid","title":"Request Id"},"external_request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Request Id"},"customer_id":{"type":"string","title":"Customer Id"},"project_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Code"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"status":{"$ref":"#/components/schemas/Status"},"total_items":{"type":"integer","title":"Total Items","description":"Items in the request; it grows while the request runs when a carousel is split into one item per video."},"counts":{"additionalProperties":{"type":"integer"},"propertyNames":{"$ref":"#/components/schemas/Status"},"type":"object","title":"Counts","description":"Items per status."},"progress_percent":{"type":"number","title":"Progress Percent"},"rate_per_min":{"type":"number","title":"Rate Per Min","description":"Items completed per minute over the last five minutes."}},"type":"object","required":["request_id","customer_id","created_at","status","total_items","counts","progress_percent","rate_per_min"],"title":"RequestSummary"},"RequestsPage":{"properties":{"requests":{"items":{"$ref":"#/components/schemas/RequestSummary"},"type":"array","title":"Requests"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Opaque; pass it back as `cursor` to get the next page. Null on the last page."}},"type":"object","required":["requests","next_cursor"],"title":"RequestsPage"},"ResultsPage":{"properties":{"results":{"items":{"$ref":"#/components/schemas/ItemResult"},"type":"array","title":"Results"},"next_cursor":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["results","next_cursor"],"title":"ResultsPage"},"Status":{"type":"string","enum":["QUEUED","WAITING","PROCESSING","RETRYING","COMPLETED","FAILED","CANCELLED","SKIPPED"],"title":"Status"},"WebhookEvent":{"$defs":{"AuditResult":{"additionalProperties":true,"description":"One audit row. Keys are the spreadsheet's column names; an empty value is \"-\".","example":{"ACCOUNT TYPE":"Owned","ARTIST POPULARITY":"Tier 4: Moderate Reach Artists","AUDIO CATEGORY":"Music Only","AUDIO STATUS":"Audio Recognized","IN TARGET LIBRARY":"No","LICENSE END DATE":"-","MATCH CONFIDENCE":"High","MUSIC DURATION (SEC)":24.8,"MUSIC PRESENCE SCORE":88.6,"MUSIC SOURCE":"Not Found in Target Libraries","PARENT POST URL":"-","PLATFORM":"Instagram","POST CAPTION":"#ad the caption","POST COMMENTS":15,"POST DATE":"2026-05-01 09:12:44","POST LIKES":141,"POST ORIGIN":"example_brand","POST TYPE":"Video","POST URL":"https://www.instagram.com/p/XXXXXXXXXXX/","REVIEW FLAG":"-","RISK STATUS":"At Risk","TRACK ARTIST":"Example Artist","TRACK ISRC":"ZZX012600001","TRACK NAME":"Example Track","TRACK RECORD LABEL":"Example Records","TRACKED ACCOUNT":"example_brand","VIDEO DURATION (SEC)":24.8},"properties":{"PLATFORM":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Platform"},"POST ORIGIN":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The account that published the post, as a handle.","title":"Post Origin"},"TRACKED ACCOUNT":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Tracked Account"},"ACCOUNT TYPE":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Owned or Collaboration.","title":"Account Type"},"PARENT POST URL":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"For a carousel slide, the carousel it belongs to; - otherwise.","title":"Parent Post Url"},"POST URL":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Post Url"},"POST DATE":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"YYYY-MM-DD HH:MM:SS (date only when the platform gives no time).","title":"Post Date"},"POST TYPE":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Video, Carousel (one slide of a multi-media post) or Image.","title":"Post Type"},"AUDIO STATUS":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Audio Recognized, Audio Not Recognized or No Audio.","title":"Audio Status"},"AUDIO CATEGORY":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Audio Category"},"IN TARGET LIBRARY":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Yes or No for a recognised track, else -.","title":"In Target Library"},"MUSIC SOURCE":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The MatchTune music source, or Not Found in Target Libraries.","title":"Music Source"},"REVIEW FLAG":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Review Required, Cross-Platform Use, or -.","title":"Review Flag"},"MATCH CONFIDENCE":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"High for a recognised track: the identification is established. Medium when two engines agreed but their agreement rests on one shared source and no fingerprint proof backs it (REVIEW FLAG Review Required). - otherwise. A post whose candidates compete or are too weak to stand alone is reported as not recognised, with no track.","title":"Match Confidence"},"RISK STATUS":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"At Risk, Compliant or Unverified.","title":"Risk Status"},"LICENSE END DATE":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"License End Date"},"TRACK NAME":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The recording the audio matched. For a re-upload published under an uploader's name, the original recording it reproduces.","title":"Track Name"},"TRACK ARTIST":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Track Artist"},"TRACK RECORD LABEL":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Track Record Label"},"TRACK ISRC":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Track Isrc"},"POST CAPTION":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Post Caption"},"VIDEO DURATION (SEC)":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"null"}],"default":null,"title":"Video Duration (Sec)"},"MUSIC DURATION (SEC)":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"null"}],"default":null,"title":"Music Duration (Sec)"},"MUSIC PRESENCE SCORE":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"null"}],"default":null,"description":"0-100.","title":"Music Presence Score"},"POST LIKES":{"anyOf":[{"type":"integer"},{"type":"string"},{"type":"null"}],"default":null,"title":"Post Likes"},"POST COMMENTS":{"anyOf":[{"type":"integer"},{"type":"string"},{"type":"null"}],"default":null,"title":"Post Comments"},"ARTIST POPULARITY":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Tier 1: Mega Artists … Tier 5: Long-Tail Artists.","title":"Artist Popularity"}},"title":"AuditResult","type":"object"},"Status":{"enum":["QUEUED","WAITING","PROCESSING","RETRYING","COMPLETED","FAILED","CANCELLED","SKIPPED"],"title":"Status","type":"string"},"WebhookEventType":{"enum":["item.completed","item.failed","request.completed"],"title":"WebhookEventType","type":"string"}},"description":"What is POSTed to callback_url. Signed with the account's webhook secret (see Callbacks).","example":{"event":"item.completed","external_id":"post-48213","external_request_id":"batch-2026-09-22-001","job_id":"b41d7e92-8c0a-4f63-9e15-2a7c6f3d8b04","metadata":{"campaign":"spring-2026","market":"FR"},"parent_job_id":null,"request_id":"3f2b8c1e-5a7d-4e9b-8c21-6d0f4a9b7e10","result":{"AUDIO STATUS":"Audio Recognized","TRACK NAME":"Example Track"},"status":"COMPLETED","timestamp":"2026-09-22T14:06:24.976633+00:00"},"properties":{"event":{"$ref":"#/components/schemas/WebhookEventType"},"request_id":{"format":"uuid","title":"Request Id","type":"string"},"external_request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"External Request Id"},"job_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"description":"Present for item events.","title":"Job Id"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"External Id"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"For item events: Your own attributes for this post, exactly as you sent them with the item; returned on the item, with its result and in webhooks.","title":"Metadata"},"parent_job_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"description":"Present when the item is a carousel slide split out of another item.","title":"Parent Job Id"},"status":{"$ref":"#/components/schemas/Status"},"result":{"anyOf":[{"$ref":"#/components/schemas/AuditResult"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"The audit row for item.completed; null otherwise.","title":"Result"},"error":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"For item.failed: class, stage and a customer-readable message.","title":"Error"},"timestamp":{"format":"date-time","title":"Timestamp","type":"string"}},"required":["event","request_id","status","timestamp"],"title":"WebhookEvent","type":"object"}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","description":"Your API key, as issued by MatchTune.","in":"header","name":"X-API-Key"},"BearerAuth":{"type":"http","description":"The same API key, as a Bearer token.","scheme":"bearer"}}},"tags":[{"name":"requests","description":"A request is a batch of posts submitted together."},{"name":"items","description":"An item is one post inside a request, identified by its job_id."}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}]}