{"openapi":"3.1.0","info":{"title":"Medialyst.ai API","description":"Development documentation","version":"1.0.0"},"servers":[{"url":"https://medialyst.ai","description":"API server"}],"paths":{"/api/health":{"get":{"responses":{"200":{"description":"OK"}},"operationId":"getApiHealth","tags":["Health"],"parameters":[],"summary":"Health check","description":"Returns 200 if the server is healthy"}},"/api/v1/credits/balance":{"get":{"responses":{"200":{"description":"Credit balance"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"429":{"description":"Free-tier public API access is temporarily paused due to high traffic"}},"operationId":"getApiV1CreditsBalance","tags":["Medialyst API"],"parameters":[],"summary":"Get credit balance","description":"Return the authenticated organization's current credit balance. Use this before cost-incurring API calls."}},"/api/v1/journalist-moves":{"get":{"responses":{"200":{"description":"A bounded, de-duplicated journalist-move page","content":{"application/json":{"schema":{"type":"object","properties":{"moves":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^jm_[A-Za-z0-9_-]{24}$"},"name":{"type":"string"},"normalized_name":{"type":["string","null"]},"old_outlet":{"type":["string","null"]},"new_outlet":{"type":["string","null"]},"kind":{"type":"string","minLength":1,"maxLength":32},"role":{"type":["string","null"]},"beat":{"type":["string","null"]},"effective_date_text":{"type":["string","null"]},"match_state":{"type":"string","minLength":1,"maxLength":64},"journalist_identity_id":{"type":["string","null"]},"observed_at":{"type":"string","format":"date-time"},"published_at":{"type":["string","null"],"format":"date-time"},"sources":{"type":"array","items":{"type":"object","properties":{"source_id":{"type":"string","minLength":1,"maxLength":128},"source_url":{"type":["string","null"],"format":"uri","maxLength":2048},"evidence_quote":{"type":"string"},"observed_at":{"type":"string","format":"date-time"},"published_at":{"type":["string","null"],"format":"date-time"},"kind":{"type":"string","minLength":1,"maxLength":32},"match_state":{"type":"string","minLength":1,"maxLength":64},"extraction_lane":{"type":"string","minLength":1,"maxLength":64}},"required":["source_id","source_url","evidence_quote","observed_at","published_at","kind","match_state","extraction_lane"],"additionalProperties":false},"minItems":1}},"required":["id","name","normalized_name","old_outlet","new_outlet","kind","role","beat","effective_date_text","match_state","journalist_identity_id","observed_at","published_at","sources"],"additionalProperties":false}},"page":{"type":"object","properties":{"count":{"type":"integer","minimum":0,"maximum":250},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","minLength":1,"maxLength":2048},"watermark":{"type":"string","format":"date-time"}},"required":["count","has_more","next_cursor","watermark"],"additionalProperties":false},"request_id":{"type":"string","minLength":1}},"required":["moves","page","request_id"],"additionalProperties":false}}}},"400":{"description":"Invalid timestamp, cursor, or limit"},"401":{"description":"Missing or invalid credential"},"403":{"description":"Credential's organization is not on an active Scale plan"},"429":{"description":"Rate limited or free-tier traffic temporarily shed"}},"operationId":"getApiV1Journalist-moves","tags":["Medialyst API"],"parameters":[{"in":"query","name":"since","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"cursor","schema":{"type":"string","minLength":1,"maxLength":2048}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":250,"default":100}},{"in":"query","name":"kind","schema":{"type":"string","minLength":1,"maxLength":64}}],"summary":"Poll journalist outlet moves","description":"Return de-duplicated journalist outlet-move records observed after an exclusive timestamp or opaque cursor. `since` filters on when Medialyst observed each move — not the move's effective date — so a poller receives late-reported moves. Results are ordered by observed_at then stable id and collapse corroborating sources into one record. Each record carries `kind` (move, promotion, departure; filter with the optional `kind` query param) and `match_state`, which only says whether the name resolved to a Medialyst journalist record — not whether the move is real. Requires an active Scale-plan credential; calls are free and cost 0 credits."}},"/api/v1/news/search":{"post":{"responses":{"200":{"description":"News search response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"link":{"type":"string"},"url_status":{"type":"string","enum":["publisher","opaque"],"description":"Whether link is a publisher URL or an opaque wrapper; opaque means the link is a Google News redirect wrapper, not a publisher URL."},"metadata":{"type":"object","properties":{"publication_type":{"type":"string","nullable":true,"enum":["editorial","brand_content","newswire","government","syndication_platform","other",null]},"domain_authority":{"type":"number","nullable":true},"estimated_monthly_organic_traffic":{"type":"number","nullable":true}},"required":["publication_type","domain_authority","estimated_monthly_organic_traffic"],"additionalProperties":true}},"additionalProperties":true}},"results":{"type":"array","items":{"type":"object","properties":{"link":{"type":"string"},"url_status":{"type":"string","enum":["publisher","opaque"],"description":"Whether link is a publisher URL or an opaque wrapper; opaque means the link is a Google News redirect wrapper, not a publisher URL."},"metadata":{"type":"object","properties":{"publication_type":{"type":"string","nullable":true,"enum":["editorial","brand_content","newswire","government","syndication_platform","other",null]},"domain_authority":{"type":"number","nullable":true},"estimated_monthly_organic_traffic":{"type":"number","nullable":true}},"required":["publication_type","domain_authority","estimated_monthly_organic_traffic"],"additionalProperties":true}},"additionalProperties":true}},"news":{"type":"array","items":{"type":"object","properties":{"link":{"type":"string"},"url_status":{"type":"string","enum":["publisher","opaque"],"description":"Whether link is a publisher URL or an opaque wrapper; opaque means the link is a Google News redirect wrapper, not a publisher URL."},"metadata":{"type":"object","properties":{"publication_type":{"type":"string","nullable":true,"enum":["editorial","brand_content","newswire","government","syndication_platform","other",null]},"domain_authority":{"type":"number","nullable":true},"estimated_monthly_organic_traffic":{"type":"number","nullable":true}},"required":["publication_type","domain_authority","estimated_monthly_organic_traffic"],"additionalProperties":true}},"additionalProperties":true}},"articles":{"type":"array","items":{"type":"object","properties":{"link":{"type":"string"},"url_status":{"type":"string","enum":["publisher","opaque"],"description":"Whether link is a publisher URL or an opaque wrapper; opaque means the link is a Google News redirect wrapper, not a publisher URL."},"metadata":{"type":"object","properties":{"publication_type":{"type":"string","nullable":true,"enum":["editorial","brand_content","newswire","government","syndication_platform","other",null]},"domain_authority":{"type":"number","nullable":true},"estimated_monthly_organic_traffic":{"type":"number","nullable":true}},"required":["publication_type","domain_authority","estimated_monthly_organic_traffic"],"additionalProperties":true}},"additionalProperties":true}},"organic":{"type":"array","items":{"type":"object","properties":{"link":{"type":"string"},"url_status":{"type":"string","enum":["publisher","opaque"],"description":"Whether link is a publisher URL or an opaque wrapper; opaque means the link is a Google News redirect wrapper, not a publisher URL."},"metadata":{"type":"object","properties":{"publication_type":{"type":"string","nullable":true,"enum":["editorial","brand_content","newswire","government","syndication_platform","other",null]},"domain_authority":{"type":"number","nullable":true},"estimated_monthly_organic_traffic":{"type":"number","nullable":true}},"required":["publication_type","domain_authority","estimated_monthly_organic_traffic"],"additionalProperties":true}},"additionalProperties":true}}},"additionalProperties":true}}}},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"},"402":{"description":"Payment Required"},"429":{"description":"Rate limited"},"500":{"description":"Internal configuration or billing error"}},"operationId":"postApiV1NewsSearch","tags":["Medialyst API"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"required":["q"],"properties":{"q":{"type":"string","description":"News search query."},"gl":{"type":"string","description":"Country code, such as us."},"hl":{"type":"string","description":"Interface language, such as en."},"page":{"type":"integer","minimum":1,"maximum":10,"description":"1-based page. Each page returns up to 10 results."},"tbs":{"type":"string","description":"Time filter, such as qdr:m."}}},"example":{"q":"\"AI infrastructure\" startup funding","gl":"us","page":2,"tbs":"qdr:m"}}}},"summary":"News search","description":"Search current news results for a query. Use page for deeper results; each page returns up to 10 items. Responses include news results plus Medialyst source classification metadata when available."}},"/api/v1/pr-calendar/query":{"post":{"responses":{"200":{"description":"PR calendar query response"},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"429":{"description":"Rate limited"}},"operationId":"postApiV1Pr-calendarQuery","tags":["Medialyst API"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","minLength":1,"maxLength":500},"industries":{"type":"array","items":{"type":"string","enum":["tech","fin","health","retail","media","food"]},"minItems":1,"maxItems":6},"types":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":25},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":25},"audiences":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":25},"country_codes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":25},"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"end_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"pitch_start_before":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"pitch_deadline_after":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25},"cursor":{"type":"string","minLength":1,"maxLength":500}},"additionalProperties":false}}}},"summary":"Query PR calendar","description":"Query Medialyst's PR calendar for source-backed awareness days, conferences, retail peaks, and cultural moments. Successful calls are free and cost 0 credits."}},"/api/v1/journalists/enrich":{"post":{"responses":{"200":{"description":"Completed idempotent replay"},"202":{"description":"Enrichment job accepted"},"400":{"description":"Invalid request, including PUBLICATION_NOT_FOUND when a publication-only reference cannot be mapped to a unique domain"},"401":{"description":"Unauthorized"},"402":{"description":"Payment Required"},"403":{"description":"Forbidden"},"409":{"description":"Idempotency conflict"},"429":{"description":"Too many active jobs"},"500":{"description":"Failed to start enrichment job"}},"operationId":"postApiV1JournalistsEnrich","tags":["Medialyst API"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"example":{"from":[{"type":"journalist_reference","name":"Jane Doe","publication":"The Daily Example"}]}}}},"summary":"Enrich journalists from references or source articles","description":"Submit journalist_reference sources or article_url sources and immediately receive a durable enrichment job. Each journalist_reference requires name plus at least one of publication, domain, or URL. Publication-only references are mapped to a canonical domain when the publication is known; otherwise the request returns PUBLICATION_NOT_FOUND and should be retried with domain supplied. Poll GET /v1/journalist-enrichment-jobs/:jobId until the job is complete or failed. Include fit_context.pitch to also receive current journalist_research_v1 fit score, reasoning, and personalized angle results."}},"/api/v1/journalist-enrichment-jobs/{jobId}":{"get":{"responses":{"200":{"description":"Journalist enrichment job"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"}},"operationId":"getApiV1Journalist-enrichment-jobsByJobId","tags":["Medialyst API"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"jobId","required":true}],"summary":"Get journalist enrichment job status"}},"/api/v1/publications/lookup":{"get":{"responses":{"200":{"description":"Publication metadata"},"400":{"description":"Invalid URL or request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"429":{"description":"Rate limited"},"500":{"description":"Configuration error"},"502":{"description":"Provider lookup failed"}},"operationId":"getApiV1PublicationsLookup","tags":["Medialyst API"],"parameters":[{"in":"query","name":"url","schema":{"type":"string","minLength":1},"required":true},{"in":"query","name":"force_refresh","schema":{"anyOf":[{"type":"string","const":"true"},{"type":"string","const":"false"},{"type":"string","const":"1"},{"type":"string","const":"0"}]},"required":false}],"summary":"Lookup publication metadata","description":"Resolve a URL to Medialyst publication metadata. Cached rows are reused while fresh; stale or missing metrics are scraped through the publication metrics pipeline and written back."}},"/api/v1/publications/lookup:batch":{"post":{"responses":{"200":{"description":"Publication metadata batch results"},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"429":{"description":"Rate limited"},"500":{"description":"Configuration error"},"502":{"description":"Provider lookup failed"}},"operationId":"postApiV1PublicationsLookup:batch","tags":["Medialyst API"],"parameters":[{"in":"query","name":"force_refresh","schema":{"anyOf":[{"type":"string","const":"true"},{"type":"string","const":"false"},{"type":"string","const":"1"},{"type":"string","const":"0"}]}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"urls":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":25}},"required":["urls"],"additionalProperties":false}}}},"summary":"Batch lookup publication metadata","description":"Resolve up to 25 URLs to publication metadata. Results preserve input order and report per-URL errors so agents can continue after partial failures."}},"/api/v1/articles/lookup":{"get":{"responses":{"200":{"description":"Article lookup result"},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"},"402":{"description":"Payment Required"},"403":{"description":"Forbidden"},"429":{"description":"Rate limited"},"500":{"description":"Configuration error"},"502":{"description":"Article lookup failed"}},"operationId":"getApiV1ArticlesLookup","tags":["Medialyst API"],"parameters":[{"in":"query","name":"url","required":true,"description":"Absolute http(s) URL of the article to look up, e.g. https://example.com/story.","schema":{"type":"string","minLength":1}},{"in":"query","name":"include","required":false,"description":"Optional. Only `markdown` is supported; it adds the extracted article body as a `markdown` field. Author details are always included by default, so there is no `authors` include.","schema":{"type":"string","enum":["markdown"]}}],"summary":"Look up article metadata and optional Markdown"}},"/api/v1/articles/lookup:batch":{"post":{"responses":{"200":{"description":"Article lookup batch results"},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"429":{"description":"Rate limited"}},"operationId":"postApiV1ArticlesLookup:batch","tags":["Medialyst API"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"urls":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":10}},"required":["urls"],"additionalProperties":false}}}},"summary":"Look up multiple articles"}},"/api/v1/media-lists:create-async":{"post":{"responses":{"202":{"description":"Job accepted"},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"},"402":{"description":"Payment Required"},"409":{"description":"Idempotency conflict"},"429":{"description":"Rate limited"}},"operationId":"postApiV1Media-lists:create-async","tags":["Medialyst API"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":2000},"topic":{"type":"string","minLength":1,"maxLength":2000},"target_list_size":{"type":"integer","minimum":1,"maximum":1000},"max_articles":{"type":"integer","minimum":1,"maximum":1000}}}}}},"summary":"Create a media list asynchronously"}},"/api/v1/jobs/{jobId}":{"get":{"responses":{"200":{"description":"Job status"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"}},"operationId":"getApiV1JobsByJobId","tags":["Medialyst API"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"jobId","required":true}],"summary":"Get media list job status"}}},"components":{"schemas":{}}}