{"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/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"},"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. 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","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"}},"/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":{}}}