Bearer authentication
Send the key only from a trusted server. It is never a browser-side approval credential.
Authorization: Bearer mm_live_…
Content-Type: application/json Public REST reference
Build on the governed marketing OS.
Connect your own tools to MarkMate through a workspace-scoped bearer key. Discover the live public catalog, inspect exact schemas, prepare human approvals, and execute with durable idempotency.
37public operations36read paths1approval paths
Disabled providers are omitted from discovery, docs, workflows, and execution.
Workspace scopedkeys cannot cross tenantsHuman approvalagents cannot approve writesIdempotentredelivery cannot double-settle
Start with discovery, not guesswork.
Create a scoped key in Settings, keep it server-side, and use the workspace id attached to that key. The public contract is available as OpenAPI 3.1 JSON.
Discover the catalog
Use the response as the source of truth for the current rollout and your key allowlist.
curl https://markmateos.com/api/v1/workspaces/WORKSPACE_ID/operations \
+ -H "Authorization: Bearer $MARKMATE_API_KEY"Five deliberate routes.
Every route is workspace-aware, capability-checked, and backed by the same registry as the app, agent, workflows, and MCP.
Discover operations
/v1/workspaces/{workspaceId}/operationsReturns only operations that are public, enabled, and allowlisted for the bearer key.
Inspect exact schemas
/v1/workspaces/{workspaceId}/operations/{opId}Returns operation metadata plus the exact input_schema and output_schema for the key.
List safe connection metadata
/v1/workspaces/{workspaceId}/connectionsReturns visible same-workspace connection metadata. Credentials are never returned.
Prepare a write
/v1/workspaces/{workspaceId}/operations/prepare-writeCreates a human-reviewable draft with statement, risk level, and approval id. It does not execute.
Run a read or approved write
/v1/workspaces/{workspaceId}/operations/runReads can run directly. Writes require an existing human approvalId and stable idempotencyKey.
The API can prepare. A human decides.
A write request is a two-step contract: prepare the exact draft, then run only after a human in the workspace has approved it. No API endpoint, AI model, webhook, or workflow listener receives approval authority.
1DiscoverGET operations and inspect its schema.
2PreparePOST prepare-write creates the review draft.
3Human approvesApproval happens in the MarkMate app.
4Execute oncePOST run with approvalId and idempotencyKey.
POST /api/v1/workspaces/WORKSPACE_ID/operations/prepare-write
{ "opId": "…", "input": { … }, "idempotencyKey": "client-run-001" }
POST /api/v1/workspaces/WORKSPACE_ID/operations/run
{ "opId": "…", "input": { … }, "approvalId": "…", "idempotencyKey": "client-run-001" }Errors are typed, bounded, and safe to retry.
Never retry a failed write blindly. Inspect the stable code and preserve the same idempotency key for a deliberate redelivery.
Authentication
Missing, expired, revoked, or invalid bearer key.
Scope
The key or workspace role lacks the requested capability or resource scope.
Unknown
The operation is disabled, private, unavailable, or not allowlisted.
Conflict
Idempotency or approval state conflicts with an existing execution.
Validation
The request or operation input failed schema validation.
Rate limit
The key or provider/workspace admission limit was reached.
Build against what is actually available.
Private and disabled providers are intentionally absent. Re-fetch discovery when your workspace or key scope changes.