API reference - Cominty Docs

The Cominty API is a standard HTTPS/JSON API for chatting with agents, managing conversation threads, handling file uploads/downloads and message exports, storing memory files in named namespaces, and configuring what a signed-in admin configures in the console: MCP integrations, agents, skills, document sources, and documents. Every endpoint below is called by the Python SDK and the JavaScript SDK. Use an SDK for the smoothest experience, or call them directly.

Base URL

https://ds.cominty.com

Authentication

Send your API token in the x-cominty-token header on every request. Create a token on the API keys page at platform.cominty.ai.

curl "https://ds.cominty.com/chat?user_id=$COMINTY_USER_ID" \
  -H "x-cominty-token: $COMINTY_API_KEY"

A key created now starts with sk-cmt-. Paste it into the header exactly as you received it, with or without a single Bearer in front. Both forms work:

x-cominty-token: sk-cmt-...
x-cominty-token: Bearer sk-cmt-...

The secret is shown once, when you create the key. Copy it then. A key created before the prefix existed has no sk-cmt- and keeps working when sent as is.

SK-CMT- (wrong case), and bearer or a double space after Bearer are all rejected. If your client adds the prefix itself, add it only when the stored value does not already start with sk-cmt-.

Authentication errors

Status	`detail`	Meaning
`403`	Starts with `Invalid COMINTY_API_KEY. A Cominty Platform secret starts with 'sk-cmt-'.`	The secret is wrong: tampered, truncated, empty, or a key from another vendor (OpenAI, Anthropic) or a session token.
`403`	`Unauthorized`	The key was archived. Create a new key instead of retrying the same one.
`403`	`Invalid token`	You sent the key in `Authorization`, which is not the key header. Send the same value in `x-cominty-token`.

Chat and threads are scoped to one end user via user_id. Chat start sends it in the body (options.user_id). Thread endpoints send it as a query parameter. The SDKs fill this in from the client, so you never pass it on those calls. Memory endpoints may accept user_id as an optional query, but it does not select a memory namespace. See Memory endpoints.

Endpoints

Method & path	Purpose
`POST /chat`	Start a thread and post the first message
`POST /chat/{thread_id}`	Post a follow-up message in a thread
`GET /chat/messages/{message_id}/stream`	Stream an assistant reply’s progress (JSONL)
`POST /chat/messages/{message_id}/cancel`	Cancel an in-flight message
`GET /chat/messages/{message_id}/export`	Export a message as a file (`pdf` or `docx`)
`GET /chat/files/upload`	Get a presigned upload permission for a new file
`POST /chat/files`	Confirm an upload, registering the file
`GET /chat/files/{file_pid}`	Get a presigned download URL for a conversation file
`GET /chat`	List threads
`GET /chat/{thread_id}`	Get a thread with its full message history
`PUT /chat/{thread_id}`	Update a thread (rename, star)
`DELETE /chat/{thread_id}`	Archive a thread
`GET /memory`	List memory files (summaries, no content)
`GET /memory/namespaces`	List namespace names that contain at least one file
`POST /memory`	Create a memory file
`GET /memory/file`	Get a memory file, including content
`PUT /memory/file`	Partially update a memory file’s content/purpose
`DELETE /memory/file`	Delete a memory file
`GET /mcp/manifest`	List the MCP integrations the key can use
`GET /agents`	List agents (summaries)
`GET /agents/models`	List the models you can put in a model chain
`GET /agents/{agent_pid}`	Get an agent with its instructions and models
`POST /agents`	Create a custom agent
`PUT /agents/{agent_pid}`	Update an agent (partial)
`PUT /agents/{agent_pid}/models`	Replace an agent’s model chain
`DELETE /agents/{agent_pid}`	Delete an agent
`GET /skills`	List skills
`POST /skills`	Create a skill from a zip
`PUT /skills/{skill_pid}`	Update a skill
`POST /skills/{skill_pid}/versions`	Upload a new version of a skill
`DELETE /skills/{skill_pid}`	Delete a skill
`GET /dc/sources`	List document sources
`POST /dc/sources`	Create a drag-and-drop source over a drive
`PUT /dc/sources/{source_pid}`	Rename a source
`PUT /dc/sources/{source_pid}/status`	Start, pause, sync, or archive a source
`POST /drives`	Create a drive
`GET /drives/{drive_pid}`	Get a drive and its files
`GET /drives/{drive_pid}/upload`	Get a presigned upload permission for a drive
`POST /drives/upload`	Confirm an upload, registering the file
`GET /files/{file_pid}`	Get a presigned download URL for a file
`DELETE /files/{file_pid}`	Delete a file
`GET /documents`	Resolve a document id from a citation

Response shapes differ per endpoint. POST /chat returns a full thread, but POST /chat/{id} returns a bare message. GET /chat/{id} returns a full thread, but PUT /chat/{id} returns a summary with no messages. GET /memory returns file summaries with no content; GET /memory/file, POST /memory, and PUT /memory/file all return the full file. Check each endpoint page for its exact response.

Memory endpoints

Memory files live in a namespace you choose. For the concepts (identity of a file, isolating users, attaching a thread), see Memory namespaces. This section covers what is specific to the endpoints. The endpoint pages list namespace as optional (max 128 characters). On the platform API it is required for create, get, update, and delete: omit it and the call returns 400 Missing namespace.

Call	`namespace` omitted	`namespace` set
`POST /memory`, `GET /memory/file`, `PUT /memory/file`, `DELETE /memory/file`	400 `Missing namespace`	That namespace
`GET /memory`	Every file in the organization	Files in that namespace only
`GET /memory/namespaces`	Every name that already has a file	-

POST /memory sends namespace in the JSON body, next to path, purpose, and content. The other memory calls send it as a query parameter. user_id may still appear as an optional query. It does not choose the namespace. A user_id in the body of POST /memory is ignored, with no error. A thread’s memory namespace is a capability: send options.capabilities.memory on POST /chat. See Capabilities. options.memory_namespace still works but is deprecated. POST /chat/{thread_id} accepts neither.

path (in POST /memory’s body, and as a query parameter everywhere else) may have at most one folder segment. "notes/todo.md" is fine, "a/b/todo.md" returns 422 ("Maximum folder depth is 1"). content may be an empty string. There’s no minimum length.

PUT /memory/file requires a version query parameter: the opaque token from your last read of that file. A stale version (the file changed since you read it) returns 409 Conflict. A malformed one (not a real timestamp) returns 422 instead. Round-trip it unchanged. Do not parse or compare it.

PUT /memory/file’s body accepts content/purpose as null, but sending null currently has no effect: the existing value is left untouched (same as omitting the key), the version doesn’t change either, and the request still returns 200. There is currently no way to clear either field once set.

DELETE /memory/file is not idempotent: deleting an already-deleted (or never-existing) path returns 404, not a repeated 204.

GET /memory/namespaces can still return stored names such as user_abc::default. They hold files written before namespaces existed. See Files written before namespaces existed.

Capabilities

Capabilities decide what the agent can use: web, indexed_documents, mcp, skills, image_generation, video_generation, music_generation, and memory. For the concepts, see Capabilities. This section covers what is specific to the endpoints.

Field	Endpoint	Lasts
`options.capabilities`	`POST /chat`	The whole thread. Frozen at start.
`message.scope`	`POST /chat` and `POST /chat/{thread_id}`	One message

curl -X POST "https://ds.cominty.com/chat" \
  -H "x-cominty-token: $COMINTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "content": "Summarize the open tickets",
      "scope": {"web": {"enabled": true}}
    },
    "options": {
      "agent_id": "'"$AGENT_ID"'",
      "user_id": "'"$COMINTY_USER_ID"'",
      "capabilities": {
        "web": {"activation": "on_request"},
        "mcp": {"activation": "always", "connections": ["linear"]},
        "memory": {"activation": "always", "namespace": "support-bot"}
      }
    }
  }'

Each capability in options.capabilities is an object with a required activation: always, on_request, or never. skills and memory accept only always and never. A never entry takes no other field.
A capability you send replaces the agent’s value entirely. An omitted filter goes back to "*" (no restriction). A capability you do not send keeps the agent’s value.
Filters (source_ids, document_ids, connections, include) are either the string "*" or a list with at least one item. null and [] return 422.
Each entry in message.scope is an object with a required enabled. The skills and memory keys return 422.
A scope can only narrow. It must stay inside the thread’s list.
options.capabilities on POST /chat/{thread_id} returns 422. The OpenAPI schema lists the field there, but a follow-up cannot change the thread.
The thread’s capabilities are not returned by any endpoint.

Thread activation	`enabled: true`	`enabled: false`	No scope
`always`	On	Off for this message	On
`on_request`	On for this message	422, already off	Off
`never`, or not set	422	422	Off

Errors

The error detail has two shapes.

Status	`detail`	Cause
422	A list of objects with `type`, `loc`, `msg`	The body is malformed: unknown key, missing `activation` or `enabled`, empty filter, or `scope.skills`
422	A string	The policy refuses the message: the scope widens a list, targets a capability the thread does not have, or turns off one that is already off

Mixing the new and the legacy fields also returns 422: options.capabilities with options.memory_namespace, or message.scope with message.disabled_tools, message.source_ids or message.document_ids. The legacy fields are deprecated and will be removed in a later version.

Ids and names in filters are not checked. An unknown source id, document id, connection name, or skill id is accepted and matches nothing.

Configure with an API key

An API key acts as an admin of its own organization. It can call the agent, skill, drive, source, and document endpoints below, and read the model catalog. These endpoints do not take user_id. For the concepts and the SDKs, see Custom agents, Skills, and Sources. This section covers what is specific to the endpoints.

Everything a key creates is owned by the user who created the key. owner on an agent and created_by on a source are that user’s id, not the key’s.
A key never sees another member’s private agents, skills, or drives. A direct read, update, or delete returns 404 Not Found, and they are absent from lists.
A key only sees its own product surface. A Platform key does not see agents created on the other surface.
Send one credential. If x-cominty-token is present, an Authorization header is ignored.

MCP endpoint

GET /mcp/manifest returns {"servers": [...]}. Use a server’s name in capabilities.mcp.connections. Servers that are off are still listed, with is_enabled false. The optional fields (connection_status, icon_uri, mcp_url, owner_id, created_at, updated_at) are omitted when unknown, not null. A manifest that cannot be loaded returns 500 with the plain text Internal Server Error, so do not parse that body as JSON.

Agent endpoints

Call	Success	Errors
`GET /agents`	200, summaries: built-in agents, organization agents, and the key owner’s private agents
`GET /agents/models`	200, a list of `{id, name}`
`GET /agents/{agent_pid}`	200, the full agent	404 `Not Found`: unknown id, another organization, or another member’s private agent
`POST /agents`	200, the agent	422: invalid body, or `skills.include` names a skill the key cannot read
`PUT /agents/{agent_pid}`	200, the agent	404 `Not Found`: also for a built-in agent
`PUT /agents/{agent_pid}/models`	200, the agent	404 `Bad model_ids`: unknown id. 422: empty list
`DELETE /agents/{agent_pid}`	204, no body	404: unknown, built-in, or already deleted

PUT /agents/{agent_pid} is partial. A JSON null clears description, instructions, and capabilities. capabilities is merged capability by capability: each one you send replaces the stored one, the others stay.
Omit model_ids on POST /agents to use the organization’s default model chain. The chain is a failover order: the first model answers.
On a built-in agent, PUT /agents/{agent_pid}/models changes the chain for the whole organization.
An organization agent owned by someone else can be updated and deleted with the key.
execution_options and memory_namespace are deprecated. Use capabilities (capabilities.memory sets the namespace).

Skill endpoints

POST /skills and POST /skills/{skill_pid}/versions are multipart/form-data. Send the zip in the file field. POST /skills also takes display_name (1 to 100 characters) and scope.

curl -X POST "https://ds.cominty.com/skills" \
  -H "x-cominty-token: $COMINTY_API_KEY" \
  -F display_name="Release notes" \
  -F scope=private \
  -F "file=@release-notes.zip;type=application/zip"

Case	Result
Created	201, the skill
`SKILL.md` at the zip root, or one top-level folder that holds it and nothing else at the root	Accepted
Any other layout	422, `detail` starts with `Invalid zip structure.`
Missing or invalid frontmatter	422, with the reason
Archive over 30 MB	413
Two uploads of one skill within the same second	500: space them out
`PUT` or `DELETE` on a built-in skill, or on a skill the key owner does not own	404 `Not Found`

DELETE /skills/{skill_pid} returns 200 with a null body and removes every version. Do not send a surface field: an API key cannot choose a surface, and the call returns 400 Forbidden field.

Source endpoints

A source indexes the files of a drive. With an API key, only store: "draganddrop" works. Creating one is a 5-step flow, like a file upload:

POST /drives returns the drive, with its id.
GET /drives/{drive_pid}/upload?filename=...&mimetype=... returns a presigned url and fields. filename cannot contain /.
POST the file to that url as multipart/form-data, with fields as form fields, and read the ETag response header. Do not send x-cominty-token to this host.
POST /drives/upload with {"etag": ..., "key": ...}. The key comes from the fields of step 2. The response is the file.
POST /dc/sources with store, scope, and config.drive_id. The first sync starts at once.

curl -X POST "https://ds.cominty.com/dc/sources" \
  -H "x-cominty-token: $COMINTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product docs",
    "store": "draganddrop",
    "scope": "private",
    "config": {"drive_id": "'"$DRIVE_ID"'"}
  }'

The response has status pending or syncing. Poll GET /dc/sources until the source is synced, then search it.

Two ids. id is a number: capabilities and scopes take it in source_ids. pid is a string: every path takes it.
No single read. There is no GET /dc/sources/{pid}. Read the list and pick. GET /dc/sources includes archived sources. archived=true keeps only those, archived=false hides them.
Files. DELETE /files/{file_pid} returns 200 with a null body. GET /files/{file_pid} returns a download URL as a bare JSON string, valid for 5 minutes. Fetch it without the key. After you add or delete a file, call the sync operation.

PUT /dc/sources/{source_pid}/status?operation=... runs one operation:

`operation`	Valid from
`start`	`paused`
`pause`	A running sync, which it cancels
`sync`	`synced`, `error`, `out_of_sync`, `daily_quota_reached`
`archive`	Any status but `archived`. It removes the indexed documents and the files, and cannot be undone.

Any other combination returns 400 Operation is not valid. An unknown operation returns 422.

Case	Result
`store` is `googledrive` or `sharepoint` with a `connection_id`	400 `Store not available for API keys`
`store` is `googledrive` or `sharepoint` without one	422
`config.drive_id` is missing or unknown	400 `Invalid config.drive_id`
A drive or file created by another user	404 `Not Found`
A 101st drive for one user	400 `Too many drives`. Drives cannot be deleted.
A 51st file on a drive	400 `Too many files` or `Too many pending files`

A source created with a key is private to the key owner. A chat that searches it must run with the owner’s user_id, as the agent’s owner shows. With another user_id, the agent’s document tool reports that it has no authorized source. See Sources.

Document endpoint

GET /documents?id=... resolves one document id, such as the one in a <cite document_id="2292#8058" .../> tag of an answer. The id contains a #, so URL-encode it (2292%238058). There is no list. An unknown id returns 404 Not Found.

curl -G "https://ds.cominty.com/documents" \
  -H "x-cominty-token: $COMINTY_API_KEY" \
  --data-urlencode "id=2292#8058"

Tool round cap

POST /chat and POST /chat/{thread_id} accept options.max_steps: an integer >= 1 that caps the tool rounds of that message. Omit it and the server applies its default (60 today, and it may change). The cap is per message and is not stored or returned. Each sub-agent has its own counter. For the behavior, see Limiting agent steps. Reaching the cap is not an error. The message ends with status success and error_code null. Continue with POST /chat/{thread_id}.

`options.max_steps`	Response
`null`	422 `int_type`
Below 1	422 `greater_than_equal`
A float	422 `int_from_float`
A non-numeric string	422 `int_parsing`

No thread or message is created when the request is rejected.

One message at a time

A thread processes one message at a time. After POST /chat or POST /chat/{thread_id}, the assistant message is pending (live: true). It only finishes when you read its events to the end with GET /chat/messages/{message_id}/stream, or when you cancel it. Until then, posting another message to the same thread returns 400:

{"detail": "Cannot process multiple messages at the same time"}

The previous message was	`POST /chat/{thread_id}`
Read to the end through the stream endpoint	200
Cancelled with `POST /chat/messages/{message_id}/cancel`, even if you never read its events	200
Never read, or the stream connection was closed early, and not cancelled	400, still pending

Closing the stream connection does not stop the message. The server keeps it pending. To free the thread:

Find the pending message: GET /chat/{thread_id} returns each message with live. A message with live: true is still pending.
Read it to the end with GET /chat/messages/{message_id}/stream, or cancel it with POST /chat/messages/{message_id}/cancel.
Post the next message.

This 400 is not the concurrency rate limit, which returns 429 Too many concurrent requests when your plan’s limit on simultaneous chats is reached.

Cancel and export a message

Call	Success	Errors
`POST /chat/messages/{message_id}/cancel`	200, the message with `status` `cancelled`	400 `Message is not live`: the message finished, failed, was already cancelled, or is a user message. 404: unknown message.
`GET /chat/messages/{message_id}/export?format=pdf`	200, the file bytes	400 `Message has no content`, for example a message still running. 404: unknown message. 422: `format` is not `pdf` or `docx`.

Cancelling is not idempotent: a second cancel returns 400. The export response carries no file name. Choose one when you save the bytes.

Files and exports

Uploading a file is a 3-step flow, not a single call:

GET /chat/files/upload: get a presigned upload permission (url + fields) for your filename/mimetype.
Upload the file directly to that url (a storage host, not ds.cominty.com) as a multipart/form-data POST, including fields as form fields alongside the file. Don’t send x-cominty-token to this URL. It’s a different host and doesn’t expect it.
POST /chat/files with the resulting ETag (as etag) and the key from step 1’s fields, to register the file and get back a ConversationFile. Its id is what feeds file_ids on POST /chat or POST /chat/{thread_id}.

GET /chat/files/{file_pid} doesn’t return file bytes. It returns a presigned download URL as a bare JSON string. Fetch that URL directly (again, no x-cominty-token needed there) to get the actual content.

GET /chat/messages/{message_id}/export returns the exported file’s raw bytes (a PDF or DOCX), not JSON. The response content-type shown on this page is a placeholder from the spec, not what you’ll actually receive.

Limits to plan for:

A file is at most 500 MiB on the hosted API. The storage host refuses a bigger one, and another deployment may set a lower limit.
Your organization has a daily upload quota. When it is used up, the storage host refuses the upload.
The download URL is short-lived (5 minutes). Fetch it right away.
No endpoint lists or deletes uploaded files.
A presigned URL carries a signature in its query string. Do not log it.

Each endpoint page below includes a live playground. Add your token and try a real request.

​Base URL

​Authentication

​Authentication errors

​Endpoints

​Memory endpoints

​Capabilities

​Errors

​Configure with an API key

​MCP endpoint

​Agent endpoints

​Skill endpoints

​Source endpoints

​Document endpoint

​Tool round cap

​One message at a time

​Cancel and export a message

​Files and exports

Base URL

Authentication

Authentication errors

Endpoints

Memory endpoints

Capabilities

Errors

Configure with an API key

MCP endpoint

Agent endpoints

Skill endpoints

Source endpoints

Document endpoint

Tool round cap

One message at a time

Cancel and export a message

Files and exports