API reference
Paths below are relative to the base URL unless they start with /api/v2. Some operations also require an eligible plan, a connected provider, or an enabled feature.
Base URL
https://withseed.app/api/v1In the table, (+ contexts:read) applies only when a Context is linked. For /ai/text, use seo:fix for SEO auto-fix and ai:edit for other edits.
| Method | Path | Required permission |
|---|---|---|
| GET | /me | Any valid credential |
| GET / POST | /drafts · /notes | drafts:read / drafts:write |
| GET / PATCH / DELETE | /drafts/{id} | drafts:read / drafts:write |
| GET | /api/v2/drafts/{id}/publishing-readiness | drafts:read + seo:score |
| GET / POST | /contexts | contexts:read / contexts:write |
| GET / PATCH / DELETE | /contexts/{id} | contexts:read / contexts:write |
| POST | /contexts/{id}/refresh | contexts:write |
| POST | /draft-setups | drafts:write (+ contexts:read) |
| GET | /draft-generation-runs/{id} | drafts:read (+ contexts:read) |
| POST | /draft-generation-runs/{id}/execute · /draft-generation-runs/{id}/retry | ai:draft + drafts:write (+ contexts:read) |
| POST | /preview | blogger:preview |
| POST | /seo-score | seo:score |
| POST | /seo-fix | seo:fix |
| POST | /drafts/generate · /ai/draft | ai:draft |
| POST | /ai/text | ai:edit / seo:fix |
| POST | /ai/article-images · /images/generate | ai:image |
| POST | /images/upload | images:upload |
| GET | /blogger/blogs · /blogger/operations/{key} | blogger:read |
| POST | /blogger/resolve-target | blogger:read |
| POST | /blogger/save-draft | blogger:draft |
| POST | /blogger/publish | blogger:publish |
| GET / POST / PATCH | /drafts/{id}/promotion-pack | social:read / social:write |
| POST | /drafts/{id}/promotion-pack/short-link | social:write |
| GET / POST | /social/destinations | social:read / social:write |
| GET | /social/publications | social:read |
| POST | /social/publish | social:publish |
| GET / POST | /social/schedules · /social/schedules/{id} | social:read / social:publish |
Before publishing, read GET /api/v2/drafts/{id}/publishing-readiness with drafts:read and seo:score. Missing title, body, or blog context blocks draft review. A missing keyword is unscored and a low SEO score is advisory. The response does not verify facts, search outcomes, or the Blogger destination, and never authorizes publishing.
Request bodies
Send JSON with Content-Type: application/json. Field names use camelCase, the same names that responses use. Draft writes also accept the earlier snake_case names (for example blog_url) so existing clients keep working; do not send both spellings of one field. Unknown fields are rejected.
POST /drafts
Create a draft. creationRequestId makes the request safe to retry: generate it once, store it, and reuse it only to resend the same body.
| Field | Type | Rule |
|---|---|---|
| creationRequestId | UUID | Required |
| title | string ≤ 200 | Optional |
| content | Markdown | Optional |
| keyword | string ≤ 100 | null | Optional |
| blogUrl | URL | null | Optional |
| postLanguage | BCP 47 | null | Optional |
| market | string ≤ 10 | Optional |
{
"creationRequestId": "6f1d2c3b-4a5e-4f60-8a7b-9c0d1e2f3a4b",
"title": "How we built it",
"content": "## Why
Markdown body",
"keyword": "web app starter kit",
"blogUrl": "https://blog.example.com/",
"postLanguage": "en"
}PATCH /drafts/{id}
Update a draft. Send expectedVersion from your latest read and only the fields you change.
| Field | Type | Rule |
|---|---|---|
| expectedVersion | integer ≥ 1 | Required |
| title | string ≤ 200 | Optional |
| content | Markdown | Optional |
| keyword | string ≤ 100 | null | Optional |
| blogUrl | URL | null | Optional |
| postLanguage | BCP 47 | null | Optional |
{ "expectedVersion": 3, "title": "A clearer title" }DELETE /drafts/{id}
Delete a draft at its current version.
| Field | Type | Rule |
|---|---|---|
| expectedVersion | integer ≥ 1 | Required |
{ "expectedVersion": 4 }POST /notes
Create a draft bound to a stable source note. Same fields as POST /drafts, plus sourceId.
| Field | Type | Rule |
|---|---|---|
| sourceId | string ≤ 300 | Required |
| creationRequestId | UUID | Required |
| title | string ≤ 200 | Optional |
| content | Markdown | Optional |
| keyword | string ≤ 100 | null | Optional |
| blogUrl | URL | null | Optional |
| postLanguage | BCP 47 | null | Optional |
| market | string ≤ 10 | Optional |
{ "sourceId": "vault/notes/launch.md", "creationRequestId": "…", "content": "Markdown body" }POST /preview
Convert Markdown to the HTML that Blogger will receive. Nothing is saved.
| Field | Type | Rule |
|---|---|---|
| content | Markdown | Required |
{ "content": "## Heading
Markdown body" }POST /seo-score
Score a title and Markdown body for a target keyword. Nothing is saved.
| Field | Type | Rule |
|---|---|---|
| content | Markdown | Required |
| title | string ≤ 200 | Optional |
| keyword | string ≤ 100 | Optional |
| postLanguage | BCP 47 | Optional |
{ "title": "How we built it", "content": "Markdown body", "keyword": "web app starter kit", "postLanguage": "en" }POST /seo-fix
Ask AI to improve one SEO dimension and return the suggested title or body; nothing is saved. A 422 response includes an outcome that explains why no fix was made. MANUAL_KEYWORD_PLACEMENT_REQUIRED means the post already has three or more H2/H3 headings and none contains the exact keyword, so place the keyword in a heading yourself.
| Field | Type | Rule |
|---|---|---|
| Idempotency-Key | string ≤ 128 | Header |
| content | Markdown | Required |
| title | string | Required |
| keyword | string | Required |
| dimensionName | titleOptimization | keywordDensity | headingStructure | contentLength | aeoOptimization | empathyIntro | Required |
| postLanguage | BCP 47 | Optional |
{ "title": "How we built it", "content": "Markdown body", "keyword": "web app starter kit", "dimensionName": "titleOptimization" }POST /images/generate
Generate one image (Pro). Provide at least one of prompt, title or content.
| Field | Type | Rule |
|---|---|---|
| Idempotency-Key | string ≤ 128 | Header |
| prompt | string ≤ 1000 | At least one of these |
| title | string ≤ 200 | At least one of these |
| content | Markdown | At least one of these |
| alt | string ≤ 160 | Optional |
| style | minimal-line | flat-illustration | 3d-clay | watercolor | retro-pixel | photoreal | Optional |
{ "prompt": "Flat illustration of modular blocks, no text", "alt": "Modular blocks", "style": "flat-illustration" }POST /blogger/resolve-target
Check which Blogger blog and post a draft would be written to. Nothing is written to Blogger.
| Field | Type | Rule |
|---|---|---|
| draftId | UUID | Required |
| expectedDraftVersion | integer ≥ 1 | Optional |
| blogId | string | Optional |
| slug | string ≤ 60 | Optional |
| labels | string[] ≤ 50 | Optional |
| allowCrossBlogDuplicate | boolean | Optional |
| blogContextConfirmation | object | Optional |
{ "draftId": "…", "expectedDraftVersion": 4, "blogId": "1234567890" }POST /blogger/publish · /blogger/save-draft
Publish the draft or save it as a Blogger draft. Resolve the target and get the user's approval first.
| Field | Type | Rule |
|---|---|---|
| Idempotency-Key | string | Header |
| draftId | UUID | Required |
| expectedDraftVersion | integer ≥ 1 | Required |
| blogId | string | Optional |
| slug | string ≤ 60 | Optional |
| labels | string[] ≤ 50 | Optional |
| allowCrossBlogDuplicate | boolean | Optional |
| blogContextConfirmation | object | Optional |
{ "draftId": "…", "expectedDraftVersion": 4, "blogId": "1234567890", "labels": ["Guides"] }Safe AI publishing workflow
Treat readiness, human approval, and the Blogger destination as separate checks. Never publish just because the readiness response says READY_FOR_REVIEW.
Keep these three concepts separate
- Blog context is the public blog whose topic and settings guide this draft. It may be a reference site, not the publishing destination.
- The writing profile supplies the user's writing preferences. The API reports only whether it is configured, not its private values.
- The Blogger destination is the connected blog that will receive the post. Resolve and confirm it separately.
Required setup
- Save a title, body, blog context, and post language on the latest draft version. A keyword is optional; without it, SEO is not scored.
- A writing profile is recommended for consistent style but does not block draft review.
- Connect Blogger in SEED and choose an available destination blog before a Blogger write.
- Grant only the API scopes needed for each read, edit, preview, or publish operation.
Publishing sequence
- Read the latest draft and its version, then request publishing-readiness.
- Resolve title, body, and blog-context blockers, then recheck after changes. Treat SEO and writing-profile advisories as suggestions, not approval or verified quality.
- Resolve the Blogger target, show the destination and current draft version to the user, and obtain explicit approval.
- Preview the final content before any Blogger write.
- Publish with expectedDraftVersion and a new stable Idempotency-Key stored before the request.
- If the result is unknown, check GET /blogger/operations/{key}. Never retry with a new key until the original outcome is known.
Readiness blockers and nextStep
- TITLE_REQUIRED / CONTENT_REQUIRED
COMPLETE_DRAFTAdd the missing title or body, save, and check the new version.- BLOG_CONTEXT_REQUIRED
SELECT_BLOG_CONTEXTAsk which public blog context should guide the draft and save its URL.
When blog context and destination differ
A 409 BLOG_CONTEXT_TARGET_MISMATCH stops the first request before any post is written to Blogger. Show expectedBlogUrl and the chosen Blogger URL to the user. After confirmation, send a new request with a new Idempotency-Key and blogId=chosenBlog.id. Build blogContextConfirmation from error.confirmation.draftId, draftVersion, and expectedBlogUrl, plus selectedBlogId=chosenBlog.id. Do not use allowCrossBlogDuplicate for this confirmation.
Stop and ask the user
- Any blocker remains, the draft version changed, or the destination is missing or unclear.
- The blog context and destination differ and the user has not confirmed the exact destination.
- The preview contains unexpected private data, unsupported claims, or content the user did not approve.
- A publish result is unknown, authentication expired, or provider access must be reconnected.
Information that is never required
Do not request, store, log, or publish API keys, access tokens, authorization codes, private notes, or profile values. SEED's scoring formula, internal prompts, abuse controls, and private business rules are not part of the public API contract.
Updating or deleting a draft or a Context requires its current expectedVersion; Blogger writes use expectedDraftVersion. Read the latest record before changing it.
AI, image, Context creation, draft setup, Blogger write, and social operations require a stable Idempotency-Key where specified by the endpoint. Store it before sending a write request. Reuse it only for the same operation and payload.
For an unknown publishing result, keep the original operation key and check its status. Do not create a new key to force another publication. Blogger results can be checked at GET /blogger/operations/{key}.
Available scopes
- drafts:read
- Read drafts
- drafts:write
- Create, edit and delete drafts
- contexts:read
- Read Contexts
- contexts:write
- Create, edit and delete Contexts
- blogger:read
- Read Blogger blogs and publishing results
- blogger:preview
- Preview Blogger HTML
- blogger:draft
- Save Blogger drafts
- blogger:publish
- Publish and update Blogger posts
- seo:score
- Evaluate SEO
- seo:fix
- Improve SEO with AI
- ai:draft
- Generate drafts and outlines with AI
- ai:edit
- Edit and translate with AI
- ai:image
- Generate images with AI
- images:upload
- Upload images
- social:read
- Read social promotion packs and publishing results
- social:write
- Create and edit social promotion packs
- social:publish
- Publish and schedule social posts
Need a hand?
Send the endpoint, HTTP status, error code, and approximate request time. Never send an API key, authorization code, token, or private note content.
Get help