Maito API Reference

The API lets users automate the same core actions they do in Maito: create drafts, schedule them, publish them, and manage documents over HTTP.

Base URL

The public API lives under /api/v1.

https://maitoai.com

Authentication

Send your API key as a bearer token on every request. The API key implicitly selects the user context.

curl -X GET "https://maitoai.com/api/v1/drafts" \
  -H "Authorization: Bearer API_KEY"

Response Format

All responses are JSON with an ok boolean. Successful responses return a data object. Failed responses return an error object with a machine-readable code and a message.

{
  "ok": true,
  "data": {
    "id": "draft_123"
  }
}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "scheduledFor is required."
  }
}

Contents

Status Codes

These are the common HTTP responses returned by the public API.

  • 400 Bad Request: payload or query validation failed.
  • 401 Unauthorized: missing or invalid API key.
  • 402 Payment Required: the user is not entitled to use the API.
  • 403 Forbidden: cross-tenant access or policy violation.
  • 404 Not Found: the requested resource does not exist.
  • 409 Conflict: the request conflicts with existing state.
  • 422 Unprocessable Entity: a domain rule rejected the request.
  • 500 Internal Error: an unexpected server error occurred.

Drafts

Drafts are typed documents you can create, revise, schedule, publish, and unschedule.

GET /api/v1/drafts

List the user's drafts.

Query parameters:

  • limit: optional integer

Example request:

curl -X GET "https://maitoai.com/api/v1/drafts?limit=20" \
  -H "Authorization: Bearer API_KEY"

Example response:

{
  "ok": true,
  "data": {
    "drafts": [
      {
        "content": {
          "id": "draft_123",
          "state": "generated_draft"
        },
        "preview": {
          "platform": "linkedin",
          "body": "We stopped treating content like a campaign..."
        }
      }
    ]
  }
}

POST /api/v1/drafts

Create a draft.

Request body:

  • body: required string
  • bodies: optional record of platform to body
  • platform: required, x or linkedin
  • metadata: optional record

Example request:

curl -X POST "https://maitoai.com/api/v1/drafts" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "linkedin",
    "body": "Three things we changed in our GTM this quarter..."
  }'

GET /api/v1/drafts/:draftId

Fetch a single draft with versions and snapshot data.

POST /api/v1/drafts/:draftId/revise

Create a new draft version.

Request body:

  • body: required string
  • platform: optional, x or linkedin
  • baseRevision: optional integer
  • parentVersionId: optional string
  • branchKey: optional string
  • metadata: optional record

POST /api/v1/drafts/:draftId/schedule

Schedule a draft to the user's default account.

Request body:

  • platform: optional, x or linkedin
  • scheduledFor: required ISO datetime

POST /api/v1/drafts/:draftId/publish

Publish a draft immediately to the user's default account.

Request body:

  • platform: optional, x or linkedin

POST /api/v1/drafts/:draftId/unschedule

Remove an existing scheduled send for a destination.

Request body:

  • destinationId: required string

Documents

Documents are the generic file system exposed by the API.

GET /api/v1/documents

List documents in the active account set.

Query parameters:

  • accountSetId: optional string
  • documentType: optional string
  • status: optional string
  • query: optional string
  • limit: optional integer

GET /api/v1/documents/by-path

Fetch a single document by path.

Query parameters:

  • path: required string
  • accountSetId: optional string

PUT /api/v1/documents/by-path

Create or update a document by path.

Request body:

  • path: required string
  • documentType: optional string when path implies type
  • status: optional string
  • title: optional string
  • bodyMarkdown: optional string
  • summary: optional string or null
  • metadata: optional record