API Quick Start

Use this path when you want a script or agent to make a small, verified change through the MONOid API.

Prerequisites

Create an API key in Settings > API Keys.
Give the key only the scopes it needs. For this guide, use tasks:read, tasks:write, containers:read, and routine_blocks:read, or a broader read + write key in a trusted local environment.
Export the key in your shell:

export MONOID_API_KEY="mo_..."
export MONOID_API_BASE_URL="https://api.usemonoid.com"

Step 1: Verify auth

curl "$MONOID_API_BASE_URL/api/v1/me" \
  -H "Authorization: Bearer $MONOID_API_KEY"

Expected shape:

{
  "data": {
    "userId": "user_abc123",
    "scopes": ["tasks:read", "tasks:write"]
  }
}

If the token is missing, malformed, expired, or revoked, the API returns 401.

Step 2: Find a container

curl "$MONOID_API_BASE_URL/api/v1/containers?limit=5" \
  -H "Authorization: Bearer $MONOID_API_KEY"

Copy one _id from the response:

{
  "data": [
    {
      "_id": "container_123",
      "name": "Work"
    }
  ],
  "meta": {
    "total": 1,
    "returned": 1,
    "limit": 5,
    "offset": 0,
    "nextCursor": null
  }
}

Step 3: Create a task

curl -X POST "$MONOID_API_BASE_URL/api/v1/tasks" \
  -H "Authorization: Bearer $MONOID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Draft weekly launch note",
    "notes": "Write the first draft and add links to supporting material.",
    "bucket": "todo",
    "containerId": "container_123",
    "doDate": "2026-06-30"
  }'

Expected shape:

{
  "data": {
    "_id": "task_123",
    "title": "Draft weekly launch note",
    "bucket": "todo",
    "containerId": "container_123",
    "doDate": "2026-06-30"
  }
}

Save the returned task _id.

Step 4: List today's tasks

curl "$MONOID_API_BASE_URL/api/v1/tasks?doDateEq=2026-06-30&limit=20" \
  -H "Authorization: Bearer $MONOID_API_KEY"

List endpoints can return pagination metadata:

{
  "data": [
    {
      "_id": "task_123",
      "title": "Draft weekly launch note",
      "bucket": "todo"
    }
  ],
  "meta": {
    "returned": 1,
    "limit": 20,
    "offset": 0,
    "nextCursor": null
  }
}

Use limit, offset, or cursor on list endpoints where supported. Limits are clamped by the API; use nextCursor when a response returns one.

Step 5: Schedule or update the task

Find a routine block for the target date:

curl "$MONOID_API_BASE_URL/api/v1/routine_blocks?date=2026-06-30&limit=10" \
  -H "Authorization: Bearer $MONOID_API_KEY"

Then assign the task to that block:

curl -X PATCH "$MONOID_API_BASE_URL/api/v1/tasks/task_123" \
  -H "Authorization: Bearer $MONOID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bucket": "in_progress",
    "routineBlockId": "routine_block_123"
  }'

Verify the change:

curl "$MONOID_API_BASE_URL/api/v1/tasks/task_123?includeNotes=false" \
  -H "Authorization: Bearer $MONOID_API_KEY"

Common failures

{
  "error": "Unauthorized"
}

400 — Request body or query parameter is invalid.
401 — API key is missing, malformed, expired, revoked, or invalid.
403 — API key is valid but lacks the required scope.
404 — Resource does not exist or is not accessible to the key.
429 — Rate limit hit. Respect the Retry-After header before retrying.
500 — Server error. Include the response x-request-id when contacting support.

Tasks — Full task endpoint reference
Routine Blocks — Find blocks for scheduling
API & Webhooks — API key setup, scopes, and revocation
CLI Quick Start — Use the same data model from the terminal

App Integrations

API Quick Start