API overview

The Adam API lets you create projects, run AI engineering tasks, manage automations, upload input files, and download the files Adam produces. The production base URL is:

https://api.adam.new/v1

The Adam API is in beta. Endpoints, schemas, behavior, and availability may change at any time without prior notice, including breaking changes. Avoid relying on it for production-critical workflows.

Connecting Claude, Codex, Cursor, or another AI client? Use the hosted Adam MCP server instead. It handles OAuth and exposes Adam as purpose-built tools.

Authentication

Create a personal API key for the workspace you want to use. Adam shows the secret once, so store it in a password manager or secret store. Send it as a Bearer token on every request:

curl https://api.adam.new/v1/projects \
  -H "Authorization: Bearer $ADAM_API_KEY"

Personal keys act as you and are restricted to the workspace and scopes chosen when the key is created. Removing you from the workspace, revoking the key, or deleting your account immediately invalidates it. You can inspect the user, workspace, scopes, and credential type associated with a key:

curl https://api.adam.new/v1/auth/context \
  -H "Authorization: Bearer $ADAM_API_KEY"

Never put an Adam API key in browser code, a mobile app, source control, or a client-side environment variable.

Billing and integrations

Keys with billing:read can retrieve a deliberately reduced subscription and usage snapshot from GET /v1/billing/summary. The response includes the effective plan, subscription state, renewal information, remaining usage percentages, and top-up balance. It does not expose payment methods, Stripe identifiers, raw credit accounting, or internal catalog IDs. Keys with integrations:read can list the integrations available to the selected workspace with GET /v1/integrations, or inspect one by stable slug with GET /v1/integrations/{integrationSlug}. Connection state reflects workspace-wide connections and the authenticated user’s own user-scoped connections. Provider credentials, account metadata, and internal connection identifiers are never returned.

Automations

Use automations:read to list and inspect scheduled or webhook-triggered automations. automations:write permits creation, editing, pausing, resuming, and permanent deletion. Automation writes still enforce the same ownership, workspace-role, subscription, trigger, and scheduling checks as the Adam app. Recurring schedules require a cron expression; one-time schedules require an ISO runAt timestamp. Webhook automations require a connected integration and a provider trigger event. Responses use effort and omit internal model-tier and provider-routing identifiers.

Idempotent writes

Adam accepts an optional Idempotency-Key when you create a project or automation and requires it when you create a task, send a message, or answer a task interaction. Use a new UUID for each logical operation and reuse it when retrying that operation. Adam replays the original response when both the key and request body match, and returns a conflict if the same key is reused for different input. Results are retained for 24 hours; using the same key after that window can execute a new request. Multipart uploads and task cancellation do not use an idempotency key.

curl https://api.adam.new/v1/projects \
  -X POST \
  -H "Authorization: Bearer $ADAM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Gearbox redesign"}'

Versions and limits

The major API version is part of the route. Compatible additions ship within /v1; breaking changes will use a new major version. Every request consumes from both a global per-key bucket and a bucket for its operation type. Responses include the selected policy in X-RateLimit-Policy and describe both buckets: Allowances are higher for workspaces with a paid subscription. These values are loaded from Adam’s current configuration; response headers remain authoritative for an individual request.

Header	Description
`X-RateLimit-Limit`	Capacity of the selected operation policy
`X-RateLimit-Remaining`	Whole requests currently available under that policy
`X-RateLimit-Reset`	Unix timestamp when that policy bucket will be full again
`X-RateLimit-Global-Limit`	Capacity shared by all operations using the key
`X-RateLimit-Global-Remaining`	Whole requests currently available globally
`X-RateLimit-Global-Reset`	Unix timestamp when the global bucket will be full again

The buckets refill continuously, so remaining quota can increase before the reset timestamp. If either bucket cannot accept a request, Adam returns 429 with Retry-After set to the number of seconds until both buckets can accept another request. Retry-After is omitted from successful responses. All errors use one JSON shape and include a request ID you can send to support:

{
  "error": {
    "type": "invalid_request",
    "message": "Idempotency-Key header is required",
    "requestId": "019cf..."
  }
}

Asynchronous tasks

Creating a task or sending a message starts work asynchronously. Poll the task until its status is completed, failed, or cancelled. If the status is awaiting_input, read pendingInteraction and answer it with the interaction endpoint; Adam then continues the same task.

Paginate collections

Projects, tasks, task files, project files, and task messages use opaque cursor pagination. Set limit, then pass a non-null nextCursor back as cursor on the next request. Do not decode cursors or reuse one with a different endpoint. You can filter tasks by projectId or by one public status: queued, running, awaiting_input, completed, cancelled, or failed.

Delete projects, tasks, and project files

DELETE /v1/projects/{projectId} permanently deletes a project you own. Its tasks and files survive and become ungrouped. DELETE /v1/tasks/{taskId} permanently deletes an owned task and its message history. Both operations require the corresponding write scope and cannot be undone. DELETE /v1/projects/{projectId}/files/{fileId} removes a durable shared file from that project and requires both projects:write and files:write. Task files and message attachments are immutable because they form part of the task history.

Upload and attach files

Task attachments use a two-step flow. First upload the bytes with POST /v1/uploads. The returned upload ID is valid for 24 hours and is bound to the user and workspace represented by the credential.

curl https://api.adam.new/v1/uploads \
  -X POST \
  -H "Authorization: Bearer $ADAM_API_KEY" \
  -F "file=@drawing.step"

{
  "upload": {
    "id": "adam_upload_...",
    "name": "drawing.step",
    "mediaType": "model/step",
    "size": 148320,
    "expiresAt": "2026-08-27T12:00:00.000Z"
  }
}

Reference that ID when creating a task or sending a message:

curl https://api.adam.new/v1/tasks/$TASK_ID/messages \
  -X POST \
  -H "Authorization: Bearer $ADAM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "content": "Check this drawing for manufacturing problems.",
    "attachments": [{"uploadId": "adam_upload_..."}]
  }'

Uploading and attaching files requires files:write. Creating a task or sending its message also requires tasks:write. You can omit the text when the attachment itself provides enough context. To add a durable shared file directly to a project, send the multipart file to POST /v1/projects/{projectId}/files instead.

Read messages

Use GET /v1/tasks/{taskId}/messages for a paginated conversation. Messages contain typed parts; there is no separate flattened text field.

curl "https://api.adam.new/v1/tasks/$TASK_ID/messages?limit=50" \
  -H "Authorization: Bearer $ADAM_API_KEY"

{
  "messages": [
    {
      "id": "message-id",
      "role": "user",
      "createdAt": "2026-08-26T12:00:00.000Z",
      "parts": [
        {"type": "text", "text": "Check this drawing."},
        {
          "type": "file",
          "id": "file-id",
          "name": "drawing.step",
          "mediaType": "model/step",
          "downloadUrl": "https://api.adam.new/v1/files/file-id/content"
        }
      ]
    }
  ],
  "nextCursor": null
}

When nextCursor is not null, pass it as the next request’s cursor query parameter. File download URLs are absolute. You can also retrieve one file’s metadata with GET /v1/files/{fileId} before downloading its content. The message-part types returned by an Adam deployment depend on its transparency policy. Text, reasoning, and tool activity are enabled by default. Administrators can also expose files, URL sources, document sources, reasoning files, structured Adam data, provider-specific content, and model step boundaries. Disabled parts are omitted; a message with no exposed parts is omitted as well. Assistant tool activity remains in order. Every invocation has a tool_call part. A completed invocation is immediately followed by a tool_result with a success, error, or denied status.

[
  {
    "type": "tool_call",
    "toolCallId": "call-1",
    "name": "bash",
    "input": {"command": "python build.py"}
  },
  {
    "type": "tool_result",
    "toolCallId": "call-1",
    "name": "bash",
    "status": "success",
    "output": {"exitCode": 0, "stdout": "Created bracket.step"}
  }
]

Tool inputs and successful outputs are JSON values. Error results contain an error string instead of output; denied results contain neither.

Getting started

Work in Adam

CAD and integrations

Teams and billing

MCP

API reference

Help

Authentication

Billing and integrations

Automations

Idempotent writes

Versions and limits

Asynchronous tasks

Paginate collections

Delete projects, tasks, and project files

Upload and attach files

Read messages

​Authentication

​Billing and integrations

​Automations

​Idempotent writes

​Versions and limits

​Asynchronous tasks

​Paginate collections

​Delete projects, tasks, and project files

​Upload and attach files

​Read messages

Authentication

Billing and integrations

Automations

Idempotent writes

Versions and limits

Asynchronous tasks

Paginate collections

Delete projects, tasks, and project files

Upload and attach files

Read messages