Docs

API reference

Scopes are checked on every call. A key without a scope gets 403 insufficient_scope, never a partial result.

Machine-readable: https://api.smmist.com/v1/openapi.json (OpenAPI 3.1)

Conventions: JSON bodies, ISO-8601 times, cursor pagination with ?cursor=&limit= (max 100). Every POST honors Idempotency-Key; keys expire after 24 hours. The response headers X-Request-ID, Idempotent-Replayed and Retry-After are exposed to browsers.

Posts§

Method	Path	Scope	Notes
POST	/v1/posts/validate	read	Dry run with per-target issues. Writes nothing.
POST	/v1/posts	draft (+publish)	Create. Idempotency-Key required with an API key. Without publish it is stored as a draft.
GET	/v1/posts	read	List with status, account_id, from, to, label, cursor.
GET	/v1/posts/{id}	read	Post with targets, URLs and last_error.
PATCH	/v1/posts/{id}	draft	Edit while draft, pending_approval, rejected or scheduled. Re-validates and voids approval.
POST	/v1/posts/{id}/schedule	publish	Set or move publish_at.
POST	/v1/posts/{id}/publish-now	publish	Send immediately.
POST	/v1/posts/{id}/cancel	publish	Cancel every target that has not gone out.
POST	/v1/posts/{id}/targets/{tid}/retry	publish	Retry one failed target.
GET	/v1/posts/{id}/attempts	read	Each attempt with timing, step and error class.
GET	/v1/posts/{id}/events	read	Audit rows for the post plus a chain check.

POST/v1/posts/validateread
Dry run with per-target issues. Writes nothing.
POST/v1/postsdraft (+publish)
Create. Idempotency-Key required with an API key. Without publish it is stored as a draft.
GET/v1/postsread
List with status, account_id, from, to, label, cursor.
GET/v1/posts/{id}read
Post with targets, URLs and last_error.
PATCH/v1/posts/{id}draft
Edit while draft, pending_approval, rejected or scheduled. Re-validates and voids approval.
POST/v1/posts/{id}/schedulepublish
Set or move publish_at.
POST/v1/posts/{id}/publish-nowpublish
Send immediately.
POST/v1/posts/{id}/cancelpublish
Cancel every target that has not gone out.
POST/v1/posts/{id}/targets/{tid}/retrypublish
Retry one failed target.
GET/v1/posts/{id}/attemptsread
Each attempt with timing, step and error class.
GET/v1/posts/{id}/eventsread
Audit rows for the post plus a chain check.

Approvals§

Method	Path	Scope	Notes
POST	/v1/posts/{id}/submit	draft	Move a draft or rejected post to pending_approval.
POST	/v1/posts/{id}/approve	approve	Sign { content_hash?, comment? }. 409 content_changed if the hash moved.
POST	/v1/posts/{id}/reject	approve	Reject with a required comment.
GET	/v1/posts/{id}/approvals	read	Every approval request and decision.

POST/v1/posts/{id}/submitdraft
Move a draft or rejected post to pending_approval.
POST/v1/posts/{id}/approveapprove
Sign { content_hash?, comment? }. 409 content_changed if the hash moved.
POST/v1/posts/{id}/rejectapprove
Reject with a required comment.
GET/v1/posts/{id}/approvalsread
Every approval request and decision.

Media§

Method	Path	Scope	Notes
POST	/v1/media	draft	Reserve an upload: { filename, mime, bytes } → presigned PUT.
POST	/v1/media/{id}/complete	draft	Confirm the upload; probes size, type and codecs.
POST	/v1/media/import	draft	Fetch a public URL (private addresses refused).
GET	/v1/media	read	The library, newest first; ?status=&kind=&cursor=&limit=.
GET	/v1/media/{id}	read	Status and probe results.
DELETE	/v1/media/{id}	draft	Delete media no post is using.

POST/v1/mediadraft
Reserve an upload: { filename, mime, bytes } → presigned PUT.
POST/v1/media/{id}/completedraft
Confirm the upload; probes size, type and codecs.
POST/v1/media/importdraft
Fetch a public URL (private addresses refused).
GET/v1/mediaread
The library, newest first; ?status=&kind=&cursor=&limit=.
GET/v1/media/{id}read
Status and probe results.
DELETE/v1/media/{id}draft
Delete media no post is using.

Accounts and platform apps§

Method	Path	Scope	Notes
GET	/v1/platforms	public	Capabilities matrix: limits per platform.
POST	/v1/platform-apps	admin	Register your own X developer app; validated on save.
GET	/v1/platform-apps	admin	Your apps, with last4 only.
DELETE	/v1/platform-apps/{id}	admin	Remove an app no account uses.
POST	/v1/accounts/x	admin	Add an X account from user tokens on your app.
POST	/v1/accounts/connect	admin	Start OAuth; returns authorize_url.
GET	/v1/accounts	read	Accounts with status and token expiry.
GET	/v1/accounts/{id}	read	One account.
POST	/v1/accounts/{id}/verify	admin	Re-check credentials with the platform.
DELETE	/v1/accounts/{id}	admin	Disable, cancel future targets, delete secrets.

GET/v1/platformspublic
Capabilities matrix: limits per platform.
POST/v1/platform-appsadmin
Register your own X developer app; validated on save.
GET/v1/platform-appsadmin
Your apps, with last4 only.
DELETE/v1/platform-apps/{id}admin
Remove an app no account uses.
POST/v1/accounts/xadmin
Add an X account from user tokens on your app.
POST/v1/accounts/connectadmin
Start OAuth; returns authorize_url.
GET/v1/accountsread
Accounts with status and token expiry.
GET/v1/accounts/{id}read
One account.
POST/v1/accounts/{id}/verifyadmin
Re-check credentials with the platform.
DELETE/v1/accounts/{id}admin
Disable, cancel future targets, delete secrets.

Audit and keys§

Method	Path	Scope	Notes
GET	/v1/audit/verify	admin	Recompute the org's chain: { ok, head_seq, head_hash, first_bad_seq? }.
GET	/v1/me	read	The caller: org, scopes, mode.
POST	/v1/api-keys	admin	Create a key; shown once.
GET	/v1/api-keys	admin	Keys by prefix, never the secret.
DELETE	/v1/api-keys/{id}	admin	Revoke.
GET	/v1/mcp/setup	read	Server URL and ready-to-paste MCP commands.

GET/v1/audit/verifyadmin
Recompute the org's chain: { ok, head_seq, head_hash, first_bad_seq? }.
GET/v1/meread
The caller: org, scopes, mode.
POST/v1/api-keysadmin
Create a key; shown once.
GET/v1/api-keysadmin
Keys by prefix, never the secret.
DELETE/v1/api-keys/{id}admin
Revoke.
GET/v1/mcp/setupread
Server URL and ready-to-paste MCP commands.