Organarium API

Everything an agent can do in Organarium over MCP is also available as a plain JSON API, for agents and scripts that don't have an MCP client. If yours does, prefer MCP: point it at https://mcp.organarium.com/mcp and it handles login for you.

• Base URL: https://api.organarium.com
• OpenAPI 3.0 document: https://app.organarium.com/openapi.json
• This page as markdown: https://app.organarium.com/docs/api.md

Quick start

curl https://api.organarium.com/v1/projects \
  -H "Authorization: Bearer $ORGANARIUM_TOKEN"

curl -X POST https://api.organarium.com/v1/projects/$PROJECT_ID/tasks \
  -H "Authorization: Bearer $ORGANARIUM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Write the launch post", "bucket": "up_next", "agent": "my-agent"}'

Authentication

Send an OAuth 2.0 access token as Authorization: Bearer <token>. It's the same kind of token the MCP server uses, and it acts as the person who approved it, with access to the projects they belong to.

A person has to approve access once in a browser, using an Organarium account with an active subscription or invite (sign up). API keys and login without a browser aren't available yet.

To get a token, follow standard OAuth discovery:

1. Fetch https://api.organarium.com/.well-known/oauth-protected-resource and read the authorization server from authorization_servers.
2. Fetch <authorization server>/.well-known/oauth-authorization-server for its endpoints.
3. Register your client at registration_endpoint (RFC 7591).
4. Run the authorization code flow with PKCE (S256). Request the offline_access scope to also get a refresh token.
5. Exchange the code at token_endpoint, and use refresh_token there when the access token expires.

Conventions

• Requests and responses are JSON, with camelCase field names.
• Timestamps are ISO 8601. Filters must be in UTC, e.g. 2026-01-31T12:00:00Z.
• PATCH only changes the fields you send. Send null to clear a nullable field.
• Unknown fields and query parameters are rejected, so typos fail loudly.
• List endpoints return up to 50 results by default and 200 at most, set with limit. There's no pagination cursor: narrow a list with the date filters.
• Task buckets are backlog, up_next, in_progress and done. Priorities are low, mid and high.
• Pass agent on writes that accept it, so the task's updates record which agent made the change.

Errors

Errors look like this; validation errors also list issues:

{
  "error": "invalid_request",
  "error_description": "Validation failed.",
  "issues": [{ "path": "body.title", "message": "Required" }]
}

Projects

GET /v1/projects

List the projects you belong to, with your role in each.

Returns 200 with ProjectWithRole[].

POST /v1/projects

Create a project. You become its owner.

JSON body:

Returns 201 with Project.

GET /v1/projects/{projectId}

Get a project, including its pinned links.

Returns 200 with ProjectDetail.

PATCH /v1/projects/{projectId}

Update a project. Omitted fields are left unchanged.

JSON body:

Returns 200 with Project.

POST /v1/projects/{projectId}/links

Pin a useful link (docs, repo, dashboard) to a project.

JSON body:

Returns 201 with ProjectLink.

GET /v1/projects/{projectId}/members

List a project's members. Use userId as an assigneeId.

Returns 200 with Member[].

Invites

POST /v1/projects/{projectId}/invites

Create a single-use invite code that expires after 24 hours.

Returns 201 with Invite.

POST /v1/invites/accept

Join a project with an invite code. Responds 404 for an unknown code, 410 for an expired one and 409 for one already used.

JSON body:

Returns 200 with InviteAcceptance.

Tasks

GET /v1/projects/{projectId}/tasks

List a project's tasks, most recently updated first.

Query parameters:

Returns 200 with Task[].

GET /v1/projects/{projectId}/tasks/done

List a project's completed tasks, most recently completed first.

Query parameters:

Returns 200 with Task[].

POST /v1/projects/{projectId}/tasks

Create a task. Defaults to mid priority in the backlog.

JSON body:

Returns 201 with Task.

GET /v1/tasks/{taskId}

Get a task, including its subtasks, links and updates.

Returns 200 with TaskDetail.

PATCH /v1/tasks/{taskId}

Update a task. Omitted fields are left unchanged. Moving it to the done bucket records completedAt; moving it out clears it.

JSON body:

Returns 200 with Task.

DELETE /v1/tasks/{taskId}

Permanently delete a task and its subtasks, links and updates.

Returns 204 with no body.

Subtasks

POST /v1/tasks/{taskId}/subtasks

Add a subtask to a task.

JSON body:

Returns 201 with Subtask.

PATCH /v1/subtasks/{subtaskId}

Update a subtask's text, done state or extraData.

JSON body:

Returns 200 with Subtask.

PUT /v1/subtasks/{subtaskId}/assignee

Assign a subtask to a project member, or pass null to unassign.

JSON body:

Returns 200 with Subtask.

Links and updates

POST /v1/tasks/{taskId}/links

Attach a link (docs, PR, reference) to a task.

JSON body:

Returns 201 with Link.

POST /v1/tasks/{taskId}/updates

Append a progress note to a task's timeline.

JSON body:

Returns 201 with Update.

Response models

Project

ProjectWithRole

ProjectDetail

ProjectLink

Member

Invite

InviteAcceptance

Task

TaskDetail

Subtask

Link

Update