Cody AI

Delete a conversation via DELETE /conversations/{id}. PERMANENTLY DELETE a conversation and every message in it. There is no undo and no recycle bin in the API. An unknown id answers 404 rather than deleting anything. Deleting a conversation does not delete the documents it was focused on. There is no undo and no recycle bin: Cody AI's API offers no way to restore what this call removes. Cody AI allows 60 requests per minute per API key and reports the budget on every authenticated response in `x-ratelimit-limit` and `x-ratelimit-remaining`; a rejected credential consumes none of it.

Delete a document via DELETE /documents/{id}. PERMANENTLY DELETE a document from the knowledge base. There is no undo and no recycle bin in the API; the bots that learned from it stop having it. An unknown id answers 404 rather than deleting anything. There is no undo and no recycle bin: Cody AI's API offers no way to restore what this call removes. Cody AI allows 60 requests per minute per API key and reports the budget on every authenticated response in `x-ratelimit-limit` and `x-ratelimit-remaining`; a rejected credential consumes none of it.

List bots via GET /bots. List the bots on this Cody AI account -- each with its `id`, `name`, `description`, `model` and `created_at` (Unix seconds). Bots are created and configured in the Cody AI web app; this API only reads them. This is where a `bot_id` comes from: Create a conversation needs one. Optional `keyword` narrows the list to bots whose name partially matches it (measured 2026-09-19: `keyword=Creative` returned 1 of 2 bots, an unmatched keyword returned 0). The reply is `{"data": [...], "meta": {"pagination": {...}}}`. This is also this integration's credential probe: on the hosted connect page the key is checked here before it is stored; the dashboard form stores it as pasted, and a wrong or revoked key fails at the first call. Cody AI allows 60 requests per minute per API key and reports the budget on every authenticated response in `x-ratelimit-limit` and `x-ratelimit-remaining`; a rejected credential consumes none of it. Page size is fixed (15 records; 10 for messages) and cannot be raised, so reading a large account costs one call per page against that budget.

List conversations via GET /conversations. List the conversations on this account, each with `id`, `name`, `bot_id` and `created_at`. Filters: `bot_id` keeps only conversations using that bot -- measured 2026-09-19 to be READ for a real bot id, but an UNKNOWN bot id is silently ignored and answers the unfiltered list, so a typo looks like 'no filter' rather than 'no results'; `keyword` matches the conversation name partially; `includes=document_ids` adds a `document_ids: {"data": [...]}` block listing the documents each conversation is focused on. This is where a `conversation_id` comes from. Cody AI allows 60 requests per minute per API key and reports the budget on every authenticated response in `x-ratelimit-limit` and `x-ratelimit-remaining`; a rejected credential consumes none of it. Page size is fixed (15 records; 10 for messages) and cannot be raised, so reading a large account costs one call per page against that budget.

Get a conversation via GET /conversations/{id}. Fetch one conversation by its `id`: `name`, `bot_id`, `created_at`, and with `includes=document_ids` the documents it is focused on. An unknown id answers 404 `{"message": "Record not found."}`. Cody AI allows 60 requests per minute per API key and reports the budget on every authenticated response in `x-ratelimit-limit` and `x-ratelimit-remaining`; a rejected credential consumes none of it.

List documents via GET /documents. List the documents in this account's knowledge base, each with `id`, `name`, `status` (`syncing`, `synced` = learned, or `sync_failed`), `content_url` (a link to the stored content as HTML), `folder_id` and `created_at`. Filters: `folder_id` lists one folder's documents; `conversation_id` lists only the documents that conversation is focused on; `keyword` matches the document name partially. This is where a `document_id` comes from -- and where to poll `status` after an import, since a file or web-page import completes asynchronously. Cody AI allows 60 requests per minute per API key and reports the budget on every authenticated response in `x-ratelimit-limit` and `x-ratelimit-remaining`; a rejected credential consumes none of it. Page size is fixed (15 records; 10 for messages) and cannot be raised, so reading a large account costs one call per page against that budget.

Get a document via GET /documents/{id}. Fetch one document by its `id`: `name`, `status`, `content_url`, `folder_id`, `created_at`. This is the call to poll after an import until `status` is `synced` (or `sync_failed`). An unknown id answers 404 `Record not found.`. The document's text itself is not in the reply -- `content_url` links to it. Cody AI allows 60 requests per minute per API key and reports the budget on every authenticated response in `x-ratelimit-limit` and `x-ratelimit-remaining`; a rejected credential consumes none of it.

List folders via GET /folders. List the knowledge-base folders on this account, each with `id`, `name` and `created_at`. Optional `keyword` matches the folder name partially (measured 2026-09-19 to be READ: `renamed` returned the one matching folder, an unmatched keyword returned 0). This is where a `folder_id` comes from: every document create needs one. Folders cannot be deleted through this API -- only created, read and renamed -- so create them deliberately. Cody AI allows 60 requests per minute per API key and reports the budget on every authenticated response in `x-ratelimit-limit` and `x-ratelimit-remaining`; a rejected credential consumes none of it. Page size is fixed (15 records; 10 for messages) and cannot be raised, so reading a large account costs one call per page against that budget.

Get a folder via GET /folders/{id}. Fetch one folder by its `id`: `name` and `created_at`. An unknown id answers 404 `Record not found.`. Use List documents with `folder_id` to see what is in it. Cody AI allows 60 requests per minute per API key and reports the budget on every authenticated response in `x-ratelimit-limit` and `x-ratelimit-remaining`; a rejected credential consumes none of it.

List messages via GET /messages. List messages, each with `id`, `content`, `conversation_id`, `machine` (true for the bot's own messages), `failed_responding`, `flagged` (true when OpenAI's usage policy was violated) and `created_at`. Pass `conversation_id` to read one conversation's thread -- without it the account's messages are listed across all conversations. `includes=sources` adds the knowledge-base documents each bot message drew on; `includes=usage` adds the tokens and credits it cost. Page size is 10 here (15 elsewhere). Cody AI allows 60 requests per minute per API key and reports the budget on every authenticated response in `x-ratelimit-limit` and `x-ratelimit-remaining`; a rejected credential consumes none of it. Page size is fixed (15 records; 10 for messages) and cannot be raised, so reading a large account costs one call per page against that budget.

Get a message via GET /messages/{id}. Fetch one message by its `id`, with `includes=sources` for the documents a bot message drew on or `includes=usage` for its token and credit cost. An unknown id answers 404 `Record not found.`. Cody AI allows 60 requests per minute per API key and reports the budget on every authenticated response in `x-ratelimit-limit` and `x-ratelimit-remaining`; a rejected credential consumes none of it.

Create a conversation via POST /conversations. Start a new conversation with one of the account's bots. `name` and `bot_id` are required (measured 2026-09-19: `{}` answers 422 naming both). Optionally pass `document_ids` to FOCUS the conversation on specific documents; only documents in folders the bot can reach are accepted. The reply is the created conversation with its new `id`, which Send a message needs. Creating a conversation is free -- it spends none of the plan's message allowance until a message is sent. Cody AI answers 422 with a per-field `errors` object naming exactly what is missing or wrong. Cody AI allows 60 requests per minute per API key and reports the budget on every authenticated response in `x-ratelimit-limit` and `x-ratelimit-remaining`; a rejected credential consumes none of it.

Update a conversation via POST /conversations/{id}. Update a conversation: rename it, switch it to another bot, or replace the set of documents it is focused on. THIS IS A PARTIAL UPDATE (measured 2026-09-19): send only the fields you are changing and the rest are kept; an empty body answers 200 and changes nothing. The vendor's schema marks `name` and `bot_id` required on this call and the server does not enforce it. The record is looked up BEFORE the body is validated, so an unknown `id` answers 404 `Record not found.` whatever the body says. Note the verb: Cody updates with POST on the record's own URL, not PUT or PATCH. The record is looked up before the body is read, so a 404 `Record not found.` is about the id and a 422 is about the body. Cody AI allows 60 requests per minute per API key and reports the budget on every authenticated response in `x-ratelimit-limit` and `x-ratelimit-remaining`; a rejected credential consumes none of it.

Create a document from text via POST /documents. Add a document to the knowledge base from TEXT you supply -- plain text or HTML, up to 768 KB in `content`. `name` and `folder_id` are required (measured 2026-09-19: `{}` answers 422 naming both, although the vendor's schema marks neither). The bot learns the document asynchronously: the reply's `status` starts at `syncing` and becomes `synced` when it can be used, so read it back before relying on it. For a file that already exists, use Get an upload URL followed by Create a document from an uploaded file; for a public web page, use Create a document from a web page. Cody AI answers 422 with a per-field `errors` object naming exactly what is missing or wrong. Cody AI allows 60 requests per minute per API key and reports the budget on every authenticated response in `x-ratelimit-limit` and `x-ratelimit-remaining`; a rejected credential consumes none of it.

Create a document from an uploaded file via POST /documents/file. Register an UPLOADED file as a document, by the `key` that Get an upload URL returned. THE BYTES ARE NOT SENT THROUGH THIS CALL and cannot be sent through Agentic Fabriq at all: the file must first be PUT to the signed S3 URL by something that has the bytes, and only then does this call make Cody read it from storage. Allowed types: txt, md, rtf, pdf, ppt, pptx, pptm, doc, docx, docm, up to 100 MB. `folder_id` and `key` are required (measured 2026-09-19). A 200 means ACCEPTED, not done: the vendor says conversion can take from a couple of minutes to an hour, after which the document appears in List documents; a 429 means the account's limit of simultaneously pending imports is reached -- wait for them to finish (they time out after an hour) and retry. Cody AI answers 422 with a per-field `errors` object naming exactly what is missing or wrong. Cody AI allows 60 requests per minute per API key and reports the budget on every authenticated response in `x-ratelimit-limit` and `x-ratelimit-remaining`; a rejected credential consumes none of it.

Create a document from a web page via POST /documents/webpage. Add a document to the knowledge base by giving Cody a PUBLIC web page URL to fetch. `folder_id` and `url` are required (measured 2026-09-19: `{}` answers 422 naming both). The page must be reachable without a login: an inaccessible page answers 400 `Webpage was in-accessible`, and the vendor's first suggestion is that a firewall on the page's side is blocking its crawler. The reply is the new document with `status` `syncing`; it becomes `synced` when the bot has learned it. Cody AI answers 422 with a per-field `errors` object naming exactly what is missing or wrong. Cody AI allows 60 requests per minute per API key and reports the budget on every authenticated response in `x-ratelimit-limit` and `x-ratelimit-remaining`; a rejected credential consumes none of it.

Create a folder via POST /folders. Create a knowledge-base folder. `name` is required (measured 2026-09-19: `{}` answers 422 `The name field is required.`, although the vendor's schema marks nothing required). THERE IS NO DELETE FOR FOLDERS in this API, so a folder created here can only be renamed afterwards -- check List folders for an existing one first. Cody AI answers 422 with a per-field `errors` object naming exactly what is missing or wrong. Cody AI allows 60 requests per minute per API key and reports the budget on every authenticated response in `x-ratelimit-limit` and `x-ratelimit-remaining`; a rejected credential consumes none of it.

Update a folder via POST /folders/{id}. Rename a folder -- `name` is the only writable field and it is required (measured 2026-09-19: `{}` against a real folder answers 422 `The name field is required.`, unlike the conversation update, which accepts a partial body). The record is looked up before the body is validated: an unknown `id` with `{}` answers 404 `Record not found.`. Note the verb: Cody updates with POST on the record's own URL. The record is looked up before the body is read, so a 404 `Record not found.` is about the id and a 422 is about the body. Cody AI allows 60 requests per minute per API key and reports the budget on every authenticated response in `x-ratelimit-limit` and `x-ratelimit-remaining`; a rejected credential consumes none of it.

Send a message and get the bot's answer via POST /messages. Post a message into a conversation and receive THE BOT'S GENERATED ANSWER in the same reply -- this call waits for the model, so allow for a slow response. `content` (up to 2000 characters) and `conversation_id` are required (measured 2026-09-19: `{}` answers 422 naming both). THIS SPENDS THE ACCOUNT'S MESSAGE ALLOWANCE: a 402 means the subscription plan's 30-day message limit is reached and nothing was generated. A 500 means the generation itself failed (vendor: service overload or a network fault) -- List messages for the conversation then shows the failed message with `failed_responding` true; retrying spends another message. Each message sent counts against the Cody AI subscription's monthly message allowance, so confirm the account has headroom before sending many. Cody AI answers 422 with a per-field `errors` object naming exactly what is missing or wrong. Cody AI allows 60 requests per minute per API key and reports the budget on every authenticated response in `x-ratelimit-limit` and `x-ratelimit-remaining`; a rejected credential consumes none of it.

Send a message and get a stream URL via POST /messages/stream. Post a message into a conversation and receive a URL for a Server-Sent-Events STREAM of the bot's answer, instead of waiting for the whole answer as Send a message does. The reply is `{"data": {"stream_url": ...}}`: Agentic Fabriq always asks for the JSON form (`redirect: false`; the vendor's default 302 to the stream cannot be followed here) and DOES NOT CONSUME THE STREAM -- the caller must read it with its own SSE client (events carry `{"chunk": ...}` between `[START]` and `[END]`, and the caller must close the connection after `[END]`). If nothing reads the stream, the answer is still generated and can be read afterwards with List messages. IF CODY ANSWERS 302 REGARDLESS, Agentic Fabriq surfaces it as an error AFTER the message has been sent: the allowance is spent and the bot's answer is readable with List messages, so do not retry blind -- read the conversation first. `content` (up to 2000 characters) and `conversation_id` are required (measured 2026-09-19). THIS SPENDS THE ACCOUNT'S MESSAGE ALLOWANCE exactly as Send a message does; 402 means the plan's 30-day message limit is reached. Each message sent counts against the Cody AI subscription's monthly message allowance, so confirm the account has headroom before sending many. Cody AI answers 422 with a per-field `errors` object naming exactly what is missing or wrong. Cody AI allows 60 requests per minute per API key and reports the budget on every authenticated response in `x-ratelimit-limit` and `x-ratelimit-remaining`; a rejected credential consumes none of it.

Get an upload URL via POST /uploads/signed-url. Step one of a file import: obtain a pre-signed Amazon S3 URL to PUT the file's bytes to, plus the storage `key` that Create a document from an uploaded file then takes. `file_name` (with its extension) and `content_type` are required (measured 2026-09-19: `{}` answers 422 naming both). The reply is `{"data": {"url": ..., "key": ...}}` (measured 2026-09-19; the vendor's schema shows the two fields at the top level, but the live reply wraps them in `data` like every other Cody reply). THE URL IS A TIME-LIMITED WRITE CAPABILITY -- measured 2026-09-19 it carries an AWS signature valid for 300 seconds (`X-Amz-Expires=300`) that permits PUTs to that one key for 300 seconds (repeatable until it expires), private, and nothing else -- so hand it to the system that holds the bytes and use it promptly; a fresh one is free. Agentic Fabriq itself cannot perform the upload: no tool here carries file bytes. Nothing is created on the account until the key is registered. Cody AI answers 422 with a per-field `errors` object naming exactly what is missing or wrong. Cody AI allows 60 requests per minute per API key and reports the budget on every authenticated response in `x-ratelimit-limit` and `x-ratelimit-remaining`; a rejected credential consumes none of it.