Skip to main content

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/v1

In 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.

MethodPathRequired permission
GET/meAny valid credential
GET / POST/drafts · /notesdrafts:read / drafts:write
GET / PATCH / DELETE/drafts/{id}drafts:read / drafts:write
GET/api/v2/drafts/{id}/publishing-readinessdrafts:read + seo:score
GET / POST/contextscontexts:read / contexts:write
GET / PATCH / DELETE/contexts/{id}contexts:read / contexts:write
POST/contexts/{id}/refreshcontexts:write
POST/draft-setupsdrafts:write (+ contexts:read)
GET/draft-generation-runs/{id}drafts:read (+ contexts:read)
POST/draft-generation-runs/{id}/execute · /draft-generation-runs/{id}/retryai:draft + drafts:write (+ contexts:read)
POST/previewblogger:preview
POST/seo-scoreseo:score
POST/seo-fixseo:fix
POST/drafts/generate · /ai/draftai:draft
POST/ai/textai:edit / seo:fix
POST/ai/article-images · /images/generateai:image
POST/images/uploadimages:upload
GET/blogger/blogs · /blogger/operations/{key}blogger:read
POST/blogger/resolve-targetblogger:read
POST/blogger/save-draftblogger:draft
POST/blogger/publishblogger:publish
GET / POST / PATCH/drafts/{id}/promotion-packsocial:read / social:write
POST/drafts/{id}/promotion-pack/short-linksocial:write
GET / POST/social/destinationssocial:read / social:write
GET/social/publicationssocial:read
POST/social/publishsocial: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.

FieldTypeRule
creationRequestIdUUIDRequired
titlestring ≤ 200Optional
contentMarkdownOptional
keywordstring ≤ 100 | nullOptional
blogUrlURL | nullOptional
postLanguageBCP 47 | nullOptional
marketstring ≤ 10Optional
{
  "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.

FieldTypeRule
expectedVersioninteger ≥ 1Required
titlestring ≤ 200Optional
contentMarkdownOptional
keywordstring ≤ 100 | nullOptional
blogUrlURL | nullOptional
postLanguageBCP 47 | nullOptional
{ "expectedVersion": 3, "title": "A clearer title" }

DELETE /drafts/{id}

Delete a draft at its current version.

FieldTypeRule
expectedVersioninteger ≥ 1Required
{ "expectedVersion": 4 }

POST /notes

Create a draft bound to a stable source note. Same fields as POST /drafts, plus sourceId.

FieldTypeRule
sourceIdstring ≤ 300Required
creationRequestIdUUIDRequired
titlestring ≤ 200Optional
contentMarkdownOptional
keywordstring ≤ 100 | nullOptional
blogUrlURL | nullOptional
postLanguageBCP 47 | nullOptional
marketstring ≤ 10Optional
{ "sourceId": "vault/notes/launch.md", "creationRequestId": "…", "content": "Markdown body" }

POST /preview

Convert Markdown to the HTML that Blogger will receive. Nothing is saved.

FieldTypeRule
contentMarkdownRequired
{ "content": "## Heading

Markdown body" }

POST /seo-score

Score a title and Markdown body for a target keyword. Nothing is saved.

FieldTypeRule
contentMarkdownRequired
titlestring ≤ 200Optional
keywordstring ≤ 100Optional
postLanguageBCP 47Optional
{ "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.

FieldTypeRule
Idempotency-Keystring ≤ 128Header
contentMarkdownRequired
titlestringRequired
keywordstringRequired
dimensionNametitleOptimization | keywordDensity | headingStructure | contentLength | aeoOptimization | empathyIntroRequired
postLanguageBCP 47Optional
{ "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.

FieldTypeRule
Idempotency-Keystring ≤ 128Header
promptstring ≤ 1000At least one of these
titlestring ≤ 200At least one of these
contentMarkdownAt least one of these
altstring ≤ 160Optional
styleminimal-line | flat-illustration | 3d-clay | watercolor | retro-pixel | photorealOptional
{ "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.

FieldTypeRule
draftIdUUIDRequired
expectedDraftVersioninteger ≥ 1Optional
blogIdstringOptional
slugstring ≤ 60Optional
labelsstring[] ≤ 50Optional
allowCrossBlogDuplicatebooleanOptional
blogContextConfirmationobjectOptional
{ "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.

FieldTypeRule
Idempotency-KeystringHeader
draftIdUUIDRequired
expectedDraftVersioninteger ≥ 1Required
blogIdstringOptional
slugstring ≤ 60Optional
labelsstring[] ≤ 50Optional
allowCrossBlogDuplicatebooleanOptional
blogContextConfirmationobjectOptional
{ "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

  1. Read the latest draft and its version, then request publishing-readiness.
  2. Resolve title, body, and blog-context blockers, then recheck after changes. Treat SEO and writing-profile advisories as suggestions, not approval or verified quality.
  3. Resolve the Blogger target, show the destination and current draft version to the user, and obtain explicit approval.
  4. Preview the final content before any Blogger write.
  5. Publish with expectedDraftVersion and a new stable Idempotency-Key stored before the request.
  6. 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