{"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"}},"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/news/search":{"post":{"responses":{"200":{"description":"News search response"},"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/journalists/enrich":{"post":{"responses":{"200":{"description":"Completed idempotent replay"},"202":{"description":"Enrichment job accepted"},"400":{"description":"Invalid request"},"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":{"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"article_url"},"url":{"type":"string","format":"uri"}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"journalist_reference"},"name":{"type":"string","minLength":1},"url":{"type":"string","format":"uri"},"domain":{"type":"string","minLength":1},"publication":{"type":"string","minLength":1}},"required":["type","name"],"additionalProperties":false}]},"minItems":1,"maxItems":500},"fit_context":{"type":"object","properties":{"pitch":{"type":"string","minLength":1,"maxLength":20000}},"required":["pitch"],"additionalProperties":false},"options":{"type":"object","properties":{"include_recent":{"type":"integer","minimum":0,"maximum":20,"default":10},"wait":{"type":"boolean"},"timeout_ms":{"type":"integer","minimum":0,"maximum":30000},"external_id":{"type":"string","maxLength":255}},"additionalProperties":false,"default":{}}},"required":["from"],"additionalProperties":false}}}},"summary":"Enrich journalists from source articles","description":"Submit article URLs and immediately receive a durable enrichment job. Include fit_context.pitch to also receive current journalist_research_v1 fit score, reasoning, and personalized angle results when polling the job."}},"/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","schema":{"type":"string","minLength":1},"required":true},{"in":"query","name":"include","schema":{"type":"string"},"required":false}],"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"}}},"components":{"schemas":{}}}