API reference
All paths below are relative to the base URL. 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 | /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 /drafts/{id}/publishing-readiness with drafts:read and seo:score. A score of 80 or more means the saved draft is ready for publishing review; it is not permission to publish and does not verify a Blogger destination.
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, keyword, blog context, and post language on the latest draft version.
- Configure a default writing profile for the post language or a profile for the exact blog context.
- 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 every blocker and repeat readiness after any draft or setting change. A score of 80 or more starts review; it does not approve publication.
- 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.- KEYWORD_REQUIRED
SET_KEYWORDChoose the draft's main keyword, save, and score again.- BLOG_CONTEXT_REQUIRED
SELECT_BLOG_CONTEXTAsk which public blog context should guide the draft and save its URL.- WRITING_PROFILE_REQUIRED
CONFIGURE_WRITING_PROFILEAsk the user to configure a writing profile in SEED Settings.- SEO_BELOW_REVIEW_THRESHOLD
IMPROVE_SEO_AND_RECHECKImprove the draft, save it, and request a fresh score.
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 requires its current expected_version. Context updates use 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