Marky API

Marky is an AI social media manager. This skill is the reference for talking to it from an agent: how to authenticate, how to connect Marky's MCP server, and which tools to reach for.

The MCP is how agents drive Marky. Connect it once (see the setup pointer below) and your client gets a curated set of typed Marky tools natively — list_workspaces, create_post, schedule_post, publish_post_now, create_media_upload, submit_feedback, ... — the live list your client shows after connecting is the source of truth. When an MCP tool exists for an operation, use the tool, not curl.

The REST API shares the same auth and data and covers operations not yet exposed as MCP tools (see "REST endpoints" below). Treat it as a stopgap, not a peer: if an agent routinely needs REST for something, that is a gap in the MCP — report it with the submit_feedback tool so Marky can add the missing tool, then use REST to finish the job in the meantime.

Detail lives in references/ next to this file — each section below says when to read which. Load them as needed rather than all up front.

Base URL and auth

Base URL:  https://api.mymarky.ai/api
Auth:      Authorization: Bearer mk_live_YOUR_KEY
Version:   Marky-Version: 2026-11-03

Every REST request needs the Bearer header, and should send the Marky-Version header:

curl https://api.mymarky.ai/api/workspaces \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Marky-Version: 2026-11-03"

Always send Marky-Version: 2026-11-03 on REST calls. A request without it is served the OLDEST API version (2026-04-08), so integrations written before versioning keep working. Every shape in this skill is the current version's. Leave the header off and you get older shapes: list endpoints return {"data": [...], "has_more": ..., "next_cursor": ...} instead of {"items": [...], "next": ...}, and the removed brand fields are accepted and silently dropped instead of rejected. Each response echoes the version it was served in its own Marky-Version header. The MCP tools always use the current version, so this only matters for REST.

Error responses:

Rate limits: 100 requests per minute per org.

Not connected yet? Read references/setup.md — it covers connecting the MCP server (https://api.mymarky.ai/api/mcp, streamable HTTP) to Claude Code, Cowork, Codex, Cursor, or any other client. Interactive clients sign in with OAuth (browser consent, no key to paste — Cowork/claude.ai custom connectors use this automatically); automation (CI, scripts, headless agents) uses an mk_live_ key, which setup.md also covers creating and persisting in MARKY_API_KEY. In a Claude Code plugin install the MCP server is already bundled and reads the MARKY_API_KEY env var; for OAuth instead, register the server manually per setup.md.

The shape: everything is scoped to a workspace

Almost every resource lives under a workspace. The path always starts with the workspace id — which the nested paths still spell businesses/{business_id}:

/api/businesses/{business_id}/posts
/api/businesses/{business_id}/topics
/api/businesses/{business_id}/library
/api/businesses/{business_id}/integrations
...

So the first call you make is always list_workspaces (MCP) or GET /workspaces (REST) to get the workspace id, then you slot that id into every path after it as business_id. Only a few org-level resources (/keys, /webhooks, /feedback) sit outside a workspace.

"Business" in the API means workspace. Marky renamed businesses to workspaces. The top-level workspace calls have workspace names — MCP tools list_workspaces, get_workspace, update_workspace; REST GET|POST /workspaces and GET|PATCH|DELETE /workspaces/{workspace_id}. Everything below them kept its shape: nested paths are still /businesses/{business_id}/..., MCP tools still take a business_id argument, and responses still carry business_id — in every case that value is the workspace id. Media-upload bodies (upload_media_from_url, upload_media_from_reference, create_media_upload) take workspace_id. The old names (list_businesses, get_business, update_business, and /businesses, /businesses/{id}) are deprecated but still work, so an older script or prompt that uses them is not broken — just prefer the new names.

Pagination (list endpoints)

List endpoints (GET /workspaces, /posts, /topics, ...) return at most 20 items per page in a cursor-paginated envelope:

{ "items": [ ... ], "next": "..." }

(That is the shape with Marky-Version: 2026-11-03. Without the header you get {"data", "has_more", "next_cursor"}; see "Base URL and auth" above.)

If next is non-null, there are more results. Pass ?limit=100 to get a bigger page, or page through by passing it back as ?cursor=NEXT until next is null. This matters on the very first call: if your org has more than 20 workspaces, the one you want may not be on page 1 of GET /workspaces — use ?limit=100 (or page with the cursor) so you do not miss it. Same for finding a specific post or topic in a long history.

Opening the app for the user

When the user asks to see something (their scheduled posts, the calendar, the library), open the right page in the Marky app instead of describing it. Workspace pages live under https://app.mymarky.ai/ws/{workspace}/... — {workspace} accepts the workspace id (the business_id UUID; the human-readable slug also works, but the API does not expose it, so use the id you already have).

When an integration's status is not valid (or a platform the user wants is missing), send them to the workspace profile page (the /business/profile link above) — that's where social accounts are connected and reconnected. It is NOT under workspace settings.

Do not invent page paths (there is no /calendar at the root, for example) — anything not in this table, link https://app.mymarky.ai and let the user navigate.

Marky wants your feedback — please send it

Marky is built to be driven by AI agents, and the team relies on agents like you to report how it goes. There is a first-class channel for exactly this: the submit_feedback MCP tool. Treat sending feedback as part of the job, not an afterthought. It is low-cost (one tool call), it never blocks your work, and it is how Marky finds and fixes the rough edges agents hit.

submit_feedback (org-level, not under a workspace; over REST it is POST /feedback). Typed fields:

Returns 201 with { "id": "...", "status": "received" }. Tip: send an Idempotency-Key header so a retry never files a duplicate.

When to send feedback — three triggers:

1. IMMEDIATELY on any bug or friction — a call failed, an error was confusing, a tool did something unexpected, a workflow was harder than it should be. File it as type: "bug" with exactly what broke (the call you made and the error you got), the moment it happens, before you work around it.
2. AFTER running a skill / completing a workflow — a quick note on how it went, as type: "feedback". Did it work end to end? What was confusing or slower than expected?
3. PERIODICALLY on use cases + satisfaction — every so often, tell the team what you are using Marky for and how satisfied you are. type: "feature" for something missing, type: "feedback" for a satisfaction check-in.

Example submit_feedback call (the shape is the same for all three — vary type and message):

{
  "type": "bug",
  "message": "schedule_post returned 422 \"scheduled_publish_time must be in the future\" even though I sent a UTC time 2 hours ahead. Had to retry with an explicit Z suffix.",
  "context": {
    "environment": "claude-code",
    "error_details": "schedule_post -> 422 validation_error"
  }
}

Non-MCP scripts can send the same body over REST as POST /feedback with the mk_live_... key. Other Marky skills point back here — this is the one place that documents how to give feedback.

Session start + where state lives

Skills are amnesiac — every session starts fresh — but you have two durable stores. Use this one rule for anything worth remembering:

Marky-first, memory-fallback. If the thing has a home in the Marky workspace's two brand documents — words (voice, audience, caption rules, CTAs, tagline, the closing line) in strategy, visuals (colours, fonts, logo, imagery, content mix, post shape) in design_style — persist it there with update_workspace (read the whole document, merge, write the whole document back, confirm the wording). The product itself reads those documents, so it never goes stale inside one agent's head. If there is no field in Marky for it — an agent-only preference like a preferred TTS voice, "no code in my videos", the user's default workspace, or "stop asking me for feedback" — save it as a local memory instead. Everything else runs on sensible defaults; you only remember a deviation from a default. (There is no user.toml — this rule replaced it.)

In a plugin install ~/.marky/brand-cache.md holds a recent copy of the two documents to orient you; before your first authored content, refresh with one get_workspace call. Your default workspace and any muted prompts live in memory — read them from there. If you don't know which workspace yet, ask once and remember the choice; a stale id 404s on first use, so re-pick and re-remember.

Feedback — event-driven

Submit feedback the moment you hit a real bug or friction (the three triggers in "Marky wants your feedback" above) — this is always on. Separately, at a natural pause roughly every couple of weeks, you may ask once with AskUserQuestion whether they want to share quick feedback: Yes → collect it and POST /api/feedback (or the submit_feedback tool); No → skip; Don't ask again → save a memory and never ask again. No stored timers — if a memory says the user muted it, don't ask.

Contribution nudge — opportunistic

If the user has locally built or substantially edited a genuinely generic, reusable skill, you may offer once (AskUserQuestion) to contribute it to the community repo Marky-Team/marky-skills-community — read references/contribution-nudge.md and follow it. Never nudge on a skill carrying private prompts or client data, and never open a PR without an explicit yes and the user reviewing the sanitized diff. "Don't ask again" → save a memory.

Library file storage

Library files (notes, briefs, knowledge-base docs) live in the user's Marky account via the manage-library skill — the default. If a user explicitly wants them on local disk instead, remember that as a memory and read/write under ~/.marky/fs/<business_id>/ (/knowledge-base/services.md → ~/.marky/fs/<business_id>/knowledge-base/services.md).

Low queue

By default, if the posting queue will run dry within ~3 days, mention it once and offer to top up — in the Claude Code plugin a SessionStart hook does this automatically (GET /queue/summary, cached 6h). If the user says "stop reminding me about my queue" (or gives a different day threshold), save a memory and honor it.

How hooks find the workspace (they can't read your memory). SessionStart hooks are plain shell scripts, outside the model loop — they have no access to your memory. The one durable fact they need, the active workspace id, lives in ~/.marky/brand-cache.md (its first line, business_id: <id>), which the brand-cache hook rewrites on every get_workspace/update_workspace. So there are two views of the same fact: you read the default workspace from memory; hooks read it from brand-cache.md. That file — not a user.toml — is the machine-readable source for anything a hook must persist across sessions.

The MCP tools (the curated set)

The MCP does not mirror the whole REST API. It exposes a curated set of typed tools — the high-value content actions an autonomous agent actually needs. Everything else stays REST-only (still fully usable over REST, just not as an MCP tool). This is a deliberate allowlist on the server, so an agent holding a content key can't nuke a workspace, leak keys, or get lost in low-value per-item CRUD.

The curated tools below are the stable core. Rather than trust this list to stay perfectly in sync, read the live tool list your MCP client shows after connecting — that is the source of truth. If you need an operation that is not exposed as a tool, tell Marky with submit_feedback (missing tools get added), then call it over REST as a stopgap (see "REST endpoints" below).

Deliberately NOT tools — these stay off the MCP on purpose, so do not wait for them: the design/template flow, and the destructive/config ops (API-key create/list/revoke, webhooks, create_workspace / delete_workspace (REST POST /workspaces, DELETE /workspaces/{workspace_id}), delete_post). (Marky-side generation IS a tool now — generate_draft_posts above — but it's deprecated: author your own posts with create_post and only reach for generation when the user explicitly asks Marky to generate.)

Not yet MCP tools (REST stopgap) — remaining gaps Marky is closing. If one matters to your workflow, say so via submit_feedback; meanwhile reach them over REST: multipart media upload (same 50 MB cap as the base64 tool, but no base64 inflation) and per-item topic / category / library / file / folder GET-DELETE-UPDATE.

REST endpoints

The calls you will make most, all relative to the base URL and nested under /businesses/{business_id} (business_id = the workspace id):

• Posts — POST /posts (create: caption required, plus restrict_publish_to, media_urls, status, link (clickable on Facebook / Google Business / Pinterest — set it whenever the post has a destination), and metadata — see "Tag every post" below), GET /posts?status=NEW (list, filter by status), GET|PATCH|DELETE /posts/{post_id} (one post — GET includes publish_results), POST /posts/{post_id}/schedule (scheduled_publish_time, ISO 8601, future), POST /posts/{post_id}/queue (next open schedule slot), POST /posts/{post_id}/publish (now).
• Generate — POST /posts/generate (Marky writes on-brand drafts; returns a job_id), then poll GET /jobs/{job_id} until completed and list the new status=NEW drafts.
• Media — POST /media (multipart, field file, ≤50 MB; returns original_url to pass in media_urls).
• Integrations — GET /integrations (connected accounts; read platform + status, target only valid ones). Accounts are connected in the dashboard, never via API.
• Stats — GET /posts/{post_id}/stats, plus per-integration account/post stats.
• Workspaces — GET /workspaces (org-level list), GET|PATCH /workspaces/{id} (the PATCH is also how you set the brand: the strategy and design_style markdown documents, each replaced whole; there is no separate brand endpoint, and since 2026-11-03 no tone / palette / font / logo fields).
• Topics & schedule — GET|POST /topics, GET|PUT /posting-schedule, GET /queue (paginated), GET /queue/summary (count + next/last estimated publish times — the cheap "when does my queue run dry?" call).

Everything else — library / folders / files, reviews, templates, designs, categories, webhooks, API keys, full request/response shapes and field lists for the calls above — is in references/rest-endpoints.md. Read it when you need a resource not listed here or the exact fields of one that is.

Brand voice and memory

Marky agents get better with use because four stores carry what was learned. The duties are summarized here; references/brand-memory.md has the full protocol — file formats, cache maintenance, examples, escalation rules. Read it before your first content-creation work of a session.

Write like the business — read the two documents before drafting

Whenever YOU are about to write social content yourself (captions, hooks, hashtags, anything user-facing), first read the workspace (get_workspace / GET /workspaces/{id}) and apply it: follow the voice, audience and every caption rule in strategy (ending each caption with its closing line, once, if it names one), and design_style for anything visual. Once per session per workspace — don't draft from a generic voice and fix it later. A cached copy (~/.marky/brand-cache.md) can orient you, but it can be stale: before your first authored content of a session, make one fresh get_workspace call. Cache format and maintenance rules are in the reference.

Learn the user's style — persist critiques into the two documents

When the user critiques generated content ("too many emojis", "stop saying 'game-changer'"), fix the content in front of you AND persist the lasting preference — following the Marky-first, memory-fallback rule above. Most style critique has a home in one of the two documents (voice and caption rules in strategy; colours, imagery, logo and post shape in design_style) → write it there with update_workspace (merge, send the whole document, confirm first). A lasting preference with no home there (e.g. a preferred TTS voice) → save it as a local memory. One-off instructions are not lasting preferences. Style critique never goes to POST /feedback.

The feedback log — taste memory across sessions

~/.marky/feedback-log.jsonl records what the user actually approved, rejected, and edited on review boards. Two duties for every creation skill: append a line after every board (feedback verbatim + an items map), and scan the last ~20 entries for this workspace before you generate — lean into what won, drop what got rejected. When the same preference shows up ~3+ times, escalate it into strategy or design_style. Entry format and escalation detail are in the reference.

Performance learnings — what the NUMBERS taught us

performance-learnings.md (a per-workspace file: the Marky library file /performance-learnings.md by default, or ~/.marky/fs/<business_id>/performance-learnings.md if the user opted into local library storage) holds dated, data-backed lessons from real engagement — what the AUDIENCE rewarded, as opposed to what the user chose. Read it before drafting any batch (it outranks generic best practices — it was measured on this audience). Offer to append when a performance review shows a real pattern — show the exact lines, write only on a yes. User-taste statements go to strategy / design_style, not here. Format in the reference.

Tag every post you create — metadata

When YOU create a post, always set metadata with the dimensions that describe it — this is how future performance reviews learn what works instead of eyeballing. Posts take up to 50 string key/value pairs (key <=40 chars, value <=500 chars), returned verbatim on every read; Marky never interprets them. Use the shared vocabulary so cuts line up across posts:

Add any keys of your own — Marky stores them verbatim. When reviewing performance (review-performance), pull posts + stats and group by these keys: that's the whole point of tagging.

Platform name reference

restrict_publish_to is case-insensitive, so linkedin and linkedIn both work. The integration platform field returns these canonical strings:

These five are the common targets. The restrict_publish_to enum also accepts twitter, linkedInProfile, pinterest, googleBusiness, and youtube — but only target a platform that shows up as a valid integration on the workspace.

Media rules of thumb:

• Video posts can target all platforms.
• Image posts target all except TikTok.
• Text-only posts target only facebook and linkedIn (Instagram, TikTok, and Stories all require media).

Always read GET /businesses/{id}/integrations first and only target platforms whose status is valid.

Before you start

• Connect your social accounts in the dashboard first. This is a one-time step at app.mymarky.ai. The API sees connected accounts but cannot add new ones.
• Find your workspace id (the business_id every other call takes) with list_workspaces / GET /workspaces (or from the dashboard URL — workspace pages are app.mymarky.ai/ws/{workspace}/..., and a UUID in that slot is the workspace id).
• Posts you create via the API show up in your normal Marky queue — review them at app.mymarky.ai/ws/{business_id}/social-posts?tab=scheduled (see "Opening the app for the user" above).