The Public API

Use the public API to connect your own application or server job to Maeve. Requests use HTTPS and an Authorization: Bearer header.

The base URL is https://api.maevesocial.com. Use the versioned path shown for each endpoint in the API reference.

Prepare Authentication

Create an API key for the workspaces your integration needs. Store it in your server's secret storage and expose it to your script as MAEVE_API_KEY.

API keys and CLI login tokens are accepted as bearer credentials. Both remain subject to the user's permissions and the organization's plan. API keys also have explicit workspace grants.

Keep API requests containing credentials in server-side code. Do not embed the key in a public website or client application.

List Your Workspaces

With MAEVE_API_KEY set in your environment, run this in a Bash-compatible shell:

curl --fail-with-body https://api.maevesocial.com/v1/workspaces \
  -H "Authorization: Bearer $MAEVE_API_KEY"

Select the workspace from the response and set WORKSPACE_ID to its ID. Then read its content:

curl --fail-with-body "https://api.maevesocial.com/v1/workspaces/$WORKSPACE_ID/content" \
  -H "Authorization: Bearer $MAEVE_API_KEY"

Use returned IDs for subsequent requests. Most public operations are scoped to a workspace.

Use the Endpoint's Version

Most routes use v1. Workbench pages, spaces, folders, and content tables use v2. Changing the version in a URL does not convert a request to another API.

GET /v1/workspaces/{workspaceId}/content
GET /v2/workspaces/{workspaceId}/workbench/pages

Copy the endpoint path and payload schema from the reference for the resource you are using.

Read Responses

A standard response contains data and meta:

{
  "data": {},
  "meta": null
}

data contains the result. meta is usually null for a single resource and contains pagination details for a list.

One resource

A list, offset

A list, cursor

An error

{
  "data": {
    "id": "3f6b1c22-9d41-4a77-b0e2-8c5d1a4e9f30",
    "name": "Brie Patisserie",
    "slug": "brie-patisserie",
    "role": "manager",
    "timezone": "Australia/Melbourne"
  },
  "meta": null
}

meta is null. Nothing else changes.

Check the endpoint's response type before parsing it. A 204 response has no body, and PDF-report downloads return a file rather than a JSON envelope.

Errors use an error object:

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "content is required",
    "details": null
  }
}

Use the HTTP status and error.code in your code. Display error.message when you need a readable explanation, rather than matching its exact wording.

Fetch More Results

Check which pagination scheme the endpoint uses.

Offset metadata can look like this:

{ "limit": 20, "offset": 0, "total": 125, "hasMore": true }

Cursor metadata can look like this:

{ "limit": 50, "hasMore": true, "nextCursor": "next-cursor-token" }

Do not construct or edit cursor values. Continue with the same filters that produced the cursor. Content and inbox thread lists use offset pagination; media and Workbench collections use cursors.

Messages within an inbox thread use a separate format: meta is null, and hasMore and nextBefore appear inside data. Follow that endpoint's parameters to request older messages.

Handle Rate Limits

Limits apply per credential and route. Jobs sharing a credential can consume the same allowance. API keys also have an overall request limit.

429 Too Many Requests

HTTP/1.1 429 Too Many Requests

X-RateLimit-Limit: 120

X-RateLimit-Remaining: 0

X-RateLimit-Reset: 43

Retry-After: 60

The ceiling, per route

• Most reads120a minute
• Most writes30a minute
• Publishing and retries15a minute
• PDF reports5a minute

Reset counts seconds left in the window, not a clock time. Once you are over, the block holds for the full minute rather than easing off as the window slides, so backing off early is cheaper than being stopped.

If a request returns 429, wait for the period specified in Retry-After before trying again. Use the rate-limit response headers to pace requests rather than repeatedly retrying a blocked operation.

Retry Mutations with an Idempotency Key

For endpoints that support Idempotency-Key, generate a unique value for each intended operation and reuse it when retrying that same request. Keep the request payload unchanged.

Maeve can return the original result for a repeated operation instead of performing it again. Replayed responses include Idempotent-Replay. Check the endpoint documentation for support and conflict behavior.

A publishing request can queue work before the platform accepts the post. Read the content status afterward and check its platform link to confirm the publishing result. Do not assume a timeout means the first request failed.

Find an Endpoint

The API reference lists resource paths, parameters, and response schemas. The OpenAPI document is available at https://api.maevesocial.com/docs/openapi.json.

Use the signed-in app for social account connections, billing, workspace creation, and member invitations. API-key management routes require a browser session; a bearer key cannot manage other keys.