Skip to content
LogoLogo

API overview

Assign's public API is JSON over HTTPS. Every product operation lives under one versioned base path:

https://api.assign.so/api/v1

The web app, CLI, IDE extensions, mobile apps and MCP server all use this API, so a change made through it follows the same permissions, validation and history as one made in the product.

Authentication

CredentialWho uses itAccepted by
Personal API token (apt_…)Scripts, CI and your own integrationsProjects, Tasks, Comments, search, Discuss, My Work, Workspace events and the CLI-scoped operations
Browser sessionThe Assign web app and browser integrations on Assign's originEvery browser operation. Writes also require CSRF protection
Developer-client tokenThe Assign CLI and IDE extensions, via browser sign-in with PKCEThe same token-accessible operations plus client-specific credential operations
Native tokenAssign MobileNative-client operations

Create personal API tokens in Account settings → Security. A token belongs to one Workspace, must only be sent to api.assign.so in the Authorization header and can be revoked at any time.

curl https://api.assign.so/api/v1/cli/my-work \
  -H "Authorization: Bearer $ASSIGN_TOKEN" \
  -H "Accept: application/json"

The endpoint index lists the credentials each operation accepts. Browser sign-in and the session and CSRF model are covered in Authentication.

Conventions at a glance

  • Identifiers are opaque UUIDv7 strings. Don't infer time, tenant or type from them.
  • Timestamps are RFC 3339 in UTC. Calendar dates such as due dates are YYYY-MM-DD.
  • Pagination uses opaque cursors with bounded page sizes: next_cursor and has_more.
  • Idempotency. Retryable writes take an Idempotency-Key. Reuse it only for the identical request.
  • Concurrency. Updates take the resource revision in If-Match, and a stale revision returns 409.
  • Errors carry a stable machine-readable code, a safe message and, when available, a request ID.
  • Isolation. A resource outside your Workspace returns 404, the same as a resource that doesn't exist.

Read Conventions before you build an integration.

Resources

  • Application realtime: upcoming browser subscriptions and applied acknowledgements
  • Account: current user, sessions, tokens and connected clients
  • Workspaces: roles, settings, members and invitations
  • Projects: Projects, Statuses, members and Milestones
  • Tasks: create, update, move, relate and comment
  • Documents: collaborative content, history and Markdown
  • Attachments: direct-to-storage uploads
  • Search: Workspace-scoped content search
  • Current work: your in-progress Task across Workspaces
  • Inbox: notifications and preferences
  • Activity: Task, Project, person and Workspace history
  • People: member profiles
  • Integrations: providers, installations and Rich Entities
  • Knowledge: evidence-backed Workspace Knowledge
  • Discuss: private AI conversation
  • Agents: hired and custom Agents
  • Git-backed Documents: sync Documents with a repository

API reference

Browse the API reference for parameters, request examples and response schemas from the public contract. Reference pages marked upcoming describe accepted behavior that has not yet deployed.

OpenAPI and SDKs

The public contract is an OpenAPI 3.1 document. It is the authoritative source for request and response schemas, and the endpoint index lists every operation in it. Import it into an API client or use it to generate your own client.

Official SDKs are generated from the same document:

LanguagePackage
TypeScript@assignso/sdk (release candidate)
PHPassignso/php-sdk (not yet published on Packagist)

SDKs release on their own schedule. See Versioning.

Page totals Awaiting deployment

My Work, Workspace Document lists, Activity, Task Comments and Agent run history return total_count for the collection you can access with the selected filters, before the cursor position. Divide it by your requested page size to calculate total pages. The count can change as items change. Activity counts events before display grouping; Comments include retained deleted-comment ordinals. Totals do not allow arbitrary cursor jumps.

Suggest changes to this page