{"openapi":"3.1.0","info":{"title":"LivePublicator API","version":"1.0.0","description":"Press releases for your agency's clients: drafted by our writer or from your text, checked, published on livepublicator.com and indexed the same day. One plan: $99 a month with 10 release credits a month. Drafting is free. Publishing uses 1 credit."},"servers":[{"url":"https://livepublicator.com/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Your API key from the account area (starts with lp_live_)."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized","no_credits","revoked","plan_paused","duplicate","validation","daily_cap","not_found","conflict","server_error"]},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"},"description":"For 422: the field names and what is wrong with each."}}}}},"Release":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["drafting","draft","scheduled","review","live","removed","rejected","failed","deleted"],"description":"review: a person or the automatic check is looking at it. failed: we could not process it, send it again. deleted: the account owner deleted the draft."},"headline":{"type":"string"},"company":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":"string"}}},"preview_url":{"type":"string","description":"Private draft preview (no sign-in needed, keep it private)."},"live_url":{"type":["string","null"]},"publish_at":{"type":["string","null"],"format":"date-time"},"published_at":{"type":["string","null"],"format":"date-time"},"credit_used":{"type":"boolean"},"report_url":{"type":["string","null"],"description":"The AI report made 7 days after the release went live (null until then)."},"report_due_at":{"type":["string","null"],"format":"date-time","description":"When the day-7 AI report runs (live releases only)."},"notes":{"type":"array","items":{"type":"string"},"description":"Notes from the content check, if any."},"created_at":{"type":"string","format":"date-time"}}},"Credits":{"type":"object","properties":{"credits":{"type":"integer","description":"Release credits left (never more than 10)."},"monthly":{"type":"integer","example":10},"resets_at":{"type":["string","null"],"format":"date-time"},"plan_status":{"type":"string","enum":["active","past_due","canceled","pending"]},"published_today":{"type":"integer"},"daily_cap":{"type":"integer","example":10}}},"Report":{"type":"object","description":"The one AI report of a live API release, made 7 days after it went live.","properties":{"check_id":{"type":"string"},"domain":{"type":"string"},"status":{"type":"string","enum":["done","running","failed"]},"score":{"type":"integer","description":"How many of the 4 AI engines mention the company."},"engines":{"type":"array","items":{"type":"object","properties":{"engine":{"type":"string"},"state":{"type":"string"},"mentioned":{"type":"boolean"}}}},"report_url":{"type":"string"}}}}},"paths":{"/releases":{"post":{"summary":"Create a draft release","description":"Agency plan: send the finished release (headline, summary, body, key_facts, quote, quote_name, quote_title, contact_name, contact_title, contact_email). We check it and publish it as sent: no writer, no AI image. Every problem comes back in one 422 as error.problems [{field, problem, fix}]. validate_only: true checks without creating. Other keys can still send a brief or full_text. Drafting is free: a credit is used only when the release is published.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique string (up to 200 characters). Sending the same key with the same body again returns the first answer instead of doing it twice. Kept 24 hours.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["company_name","company_domain"],"properties":{"company_name":{"type":"string","maxLength":120},"company_domain":{"type":"string","example":"acme.com"},"brief":{"type":"string","minLength":20,"maxLength":2000,"description":"Use this or full_text."},"full_text":{"type":"string","minLength":300,"maxLength":20000,"description":"Headline on the first line, then the body (up to 800 words, headline not counted). Use this or brief."},"headline":{"type":"string","minLength":10,"maxLength":200,"description":"Ready release. One line; name the company."},"summary":{"type":"string","minLength":40,"maxLength":300,"description":"Ready release. One sentence."},"body":{"type":"string","description":"Ready release. 150 to 800 words; text, Markdown or HTML; 3 links at most; do not repeat the headline."},"body_format":{"type":"string","enum":["text","markdown","html"]},"key_facts":{"type":"array","minItems":1,"maxItems":8,"items":{"type":"string","minLength":5,"maxLength":200}},"faq":{"type":"array","maxItems":6,"items":{"type":"object","required":["question","answer"],"properties":{"question":{"type":"string"},"answer":{"type":"string"}}}},"contact_name":{"type":"string","maxLength":120},"contact_title":{"type":"string","maxLength":120,"description":"The press contact's role."},"contact_email":{"type":"string","format":"email"},"contact_phone":{"type":"string"},"client_authorized":{"type":"boolean","description":"Agencies: true confirms the client agreed that you publish this release for it."},"validate_only":{"type":"boolean","description":"Check everything and return the problems; create nothing (200 with valid: true when there are none)."},"quote":{"type":"string","maxLength":600},"quote_name":{"type":"string","maxLength":80},"quote_title":{"type":"string","maxLength":120},"image_url":{"type":"string","format":"uri","description":"https only. JPEG, PNG or WebP, up to 5 MB. 1200 px wide or more fills the page, from 600 px it shows at its own size. An image that cannot be used never blocks the release: the answer has image_note and the page shows the cover card. Use this or image_base64. With no image, the page shows a cover card with the logo and headline (we never make an AI image for API releases)."},"image_base64":{"type":"string","description":"The image itself, base64 (a data: prefix is fine). JPEG, PNG or WebP, up to 5 MB."},"publish_at":{"type":"string","format":"date-time","description":"Used when the release is published. Up to 60 days ahead."},"test":{"type":"boolean","description":"Test mode: the release goes to a private sandbox company and is never public, listed or posted. Publishing it uses no credit; about 30 seconds after publish it moves from review to published (or rejected). See /developers."},"test_outcome":{"type":"string","enum":["published","rejected"],"description":"Only with test: true. \"rejected\" shows how a rejection looks."}}}}}},"responses":{"201":{"description":"Draft created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Release"}}}},"401":{"description":"Missing or unknown key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key revoked or plan paused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Same Idempotency-Key with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error: error.fields by name, and for ready releases error.problems [{field, problem, fix}] with every problem at once","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List releases","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Newest first","content":{"application/json":{"schema":{"type":"object","properties":{"releases":{"type":"array","items":{"$ref":"#/components/schemas/Release"}}}}}}},"401":{"description":"Missing or unknown key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/releases/{id}":{"get":{"summary":"Get a release","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The release","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Release"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/releases/{id}/publish":{"post":{"summary":"Publish a draft","description":"Uses 1 credit. The release goes live after the automatic checks, or at publish_at. The first 3 releases of each new key are checked by a person first (usually within a few hours): the status is review until then.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique string (up to 200 characters). Sending the same key with the same body again returns the first answer instead of doing it twice. Kept 24 hours.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Published, scheduled or sent to review","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Release"}}}},"402":{"description":"No credits left this month","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key revoked or plan paused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Already published","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"10 releases a day per key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credits":{"get":{"summary":"Credits left","responses":{"200":{"description":"Credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credits"}}}}}}}},"webhooks":{"release.published":{"post":{"summary":"A release went live","description":"Body: { event, created_at, data: Release }. Header X-LivePublicator-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of `${t}.${raw body}` with your webhook secret>."}},"release.held":{"post":{"summary":"A release is waiting for a person to check it, or was not published","description":"Same body and signature. data.status is review or rejected, data.notes says why."}},"report.ready":{"post":{"summary":"The day-7 AI report of a release is ready","description":"Sent once per live release, 7 days after it went live. Same body and signature. data is the Report."}}}}