Sources

GET /agents/{agent_id}/sources

List an agent's sources

Every knowledge source of the agent with its indexing status, newest first.

Scope: agents:read

Parameters

• agent_id required in the path · string
• limit optional in the query · integer

  Rows per page, 1 to 100.

• cursor optional in the query · string

  The next_cursor of the previous page.

Returns Source

• id required string

  Id

• type required string

  text, file, website, sheet, qa_bulk, faq or research.

• name required string

  Name

• status required string

  uploaded, crawling, parsing, chunking, embedding, indexed or failed.

• error optional string

  Error

• size_bytes optional integer

  Size Bytes

• pages optional integer

  Pages

• chunk_count optional integer

  Chunk Count

• extracted_chars optional integer

  Characters of text read from the source at its last indexing: what it counts toward the plan's text per agent. 0 until it is indexed.

• version optional integer

  1 when created; +1 each time the source is re-saved.

• source_url optional string

  Source Url

• content_sha256 optional string

  For a text source: the SHA-256 (hex) of its stored text in UTF-8, so a client can tell whether its copy differs without downloading it. null for other kinds.

• created_at required string

  Created At

• updated_at required string

  Updated At

Responses

• 200 Successful Response
• 401 Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers key_maker_left.
• 403 The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (maker_role_limit; a publishable key says insufficient_scope).
• 404 Nothing by that id in this workspace.
• 413 The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: plan_text_limit, the agent's plan cannot hold more text (limit_chars, used_chars).
• 422 The request did not validate; details lists the fields.
• 429 Rate limit reached; wait Retry-After seconds.
• 500 Our fault; quote request_id to support.

curl https://www.bidii.ai/api/v2/agents/AGENT_ID/sources \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"

POST /agents/{agent_id}/sources

Add a text or sheet source

Give the agent text to read, or a Google Sheet to read from its published CSV. Indexing runs in the background: the answer is 202 with the source at status uploaded and a Location header; poll it until indexed. Send an Idempotency-Key so a retry never adds the source twice: the same key with the same body replays the first answer, with another body it is 422 idempotency_key_reused, and while the first request is still running it is 409 idempotency_in_progress. When the agent's plan cannot hold more text the answer is 413 plan_text_limit.

Scope: sources:write

Parameters

• agent_id required in the path · string

Request body

• type required "text" | "sheet"

  text: content you send in text. sheet: a Google Sheet published as CSV, by url. Files and websites come from the dashboard.

• name optional string

  A label, such as 'Opening hours'. Required for text.

• text optional string

  For text: what the agent should know, in any language. Markdown headings are kept.

• url optional string

  For sheet: the Google Sheets link (File > Share > Publish to web).

Returns Source

• id required string

  Id

• type required string

  text, file, website, sheet, qa_bulk, faq or research.

• name required string

  Name

• status required string

  uploaded, crawling, parsing, chunking, embedding, indexed or failed.

• error optional string

  Error

• size_bytes optional integer

  Size Bytes

• pages optional integer

  Pages

• chunk_count optional integer

  Chunk Count

• extracted_chars optional integer

  Characters of text read from the source at its last indexing: what it counts toward the plan's text per agent. 0 until it is indexed.

• version optional integer

  1 when created; +1 each time the source is re-saved.

• source_url optional string

  Source Url

• content_sha256 optional string

  For a text source: the SHA-256 (hex) of its stored text in UTF-8, so a client can tell whether its copy differs without downloading it. null for other kinds.

• created_at required string

  Created At

• updated_at required string

  Updated At

Responses

• 202 Successful Response
• 401 Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers key_maker_left.
• 403 The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (maker_role_limit; a publishable key says insufficient_scope).
• 404 Nothing by that id in this workspace.
• 413 The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: plan_text_limit, the agent's plan cannot hold more text (limit_chars, used_chars).
• 422 The request did not validate; details lists the fields.
• 429 Rate limit reached; wait Retry-After seconds.
• 500 Our fault; quote request_id to support.
• 409 conflict: the sheet is already one of this agent's sources. idempotency_in_progress: the first request with this Idempotency-Key is still running.

curl -X POST https://www.bidii.ai/api/v2/agents/AGENT_ID/sources \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "text", "name": "Opening hours", "text": "Open 9am to 6pm, Saturday to Thursday."}'

GET /agents/{agent_id}/sources/{source_id}

Get a source

One source with its status: uploaded, parsing, chunking, embedding, indexed or failed.

Scope: agents:read

Parameters

• agent_id required in the path · string
• source_id required in the path · string

Returns Source

• id required string

  Id

• type required string

  text, file, website, sheet, qa_bulk, faq or research.

• name required string

  Name

• status required string

  uploaded, crawling, parsing, chunking, embedding, indexed or failed.

• error optional string

  Error

• size_bytes optional integer

  Size Bytes

• pages optional integer

  Pages

• chunk_count optional integer

  Chunk Count

• extracted_chars optional integer

  Characters of text read from the source at its last indexing: what it counts toward the plan's text per agent. 0 until it is indexed.

• version optional integer

  1 when created; +1 each time the source is re-saved.

• source_url optional string

  Source Url

• content_sha256 optional string

  For a text source: the SHA-256 (hex) of its stored text in UTF-8, so a client can tell whether its copy differs without downloading it. null for other kinds.

• created_at required string

  Created At

• updated_at required string

  Updated At

Responses

• 200 Successful Response
• 401 Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers key_maker_left.
• 403 The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (maker_role_limit; a publishable key says insufficient_scope).
• 404 Nothing by that id in this workspace.
• 413 The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: plan_text_limit, the agent's plan cannot hold more text (limit_chars, used_chars).
• 422 The request did not validate; details lists the fields.
• 429 Rate limit reached; wait Retry-After seconds.
• 500 Our fault; quote request_id to support.

curl https://www.bidii.ai/api/v2/agents/AGENT_ID/sources/SOURCE_ID \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"

PATCH /agents/{agent_id}/sources/{source_id}

Re-save a text source

Replace the text of a text source: a new version. The old version keeps answering until the new one is indexed, then its chunks are replaced at once. 404 for a source that is not text; 409 conflict while the previous save is still being indexed.

Scope: sources:write

Parameters

• agent_id required in the path · string
• source_id required in the path · string

Request body

• name optional string

  A new label; omit to keep it.

• text required string

  The whole new text of the source.

Returns Source

• id required string

  Id

• type required string

  text, file, website, sheet, qa_bulk, faq or research.

• name required string

  Name

• status required string

  uploaded, crawling, parsing, chunking, embedding, indexed or failed.

• error optional string

  Error

• size_bytes optional integer

  Size Bytes

• pages optional integer

  Pages

• chunk_count optional integer

  Chunk Count

• extracted_chars optional integer

  Characters of text read from the source at its last indexing: what it counts toward the plan's text per agent. 0 until it is indexed.

• version optional integer

  1 when created; +1 each time the source is re-saved.

• source_url optional string

  Source Url

• content_sha256 optional string

  For a text source: the SHA-256 (hex) of its stored text in UTF-8, so a client can tell whether its copy differs without downloading it. null for other kinds.

• created_at required string

  Created At

• updated_at required string

  Updated At

Responses

• 202 Successful Response
• 401 Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers key_maker_left.
• 403 The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (maker_role_limit; a publishable key says insufficient_scope).
• 404 Nothing by that id in this workspace.
• 413 The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: plan_text_limit, the agent's plan cannot hold more text (limit_chars, used_chars).
• 422 The request did not validate; details lists the fields.
• 429 Rate limit reached; wait Retry-After seconds.
• 500 Our fault; quote request_id to support.
• 409 conflict: the previous save is still being indexed.

curl -X PATCH https://www.bidii.ai/api/v2/agents/AGENT_ID/sources/SOURCE_ID \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "..."}'

DELETE /agents/{agent_id}/sources/{source_id}

Remove a source

Remove the source and everything indexed from it. The agent stops answering from it at once.

Scope: sources:write

Parameters

• agent_id required in the path · string
• source_id required in the path · string

Responses

• 204 Successful Response
• 401 Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers key_maker_left.
• 403 The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (maker_role_limit; a publishable key says insufficient_scope).
• 404 Nothing by that id in this workspace.
• 413 The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: plan_text_limit, the agent's plan cannot hold more text (limit_chars, used_chars).
• 422 The request did not validate; details lists the fields.
• 429 Rate limit reached; wait Retry-After seconds.
• 500 Our fault; quote request_id to support.

curl -X DELETE https://www.bidii.ai/api/v2/agents/AGENT_ID/sources/SOURCE_ID \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"

GET /agents/{agent_id}/sources/{source_id}/content

Read a text source's text

The text of a text source as it is stored (what you sent, trimmed), with its content_sha256 and version. Only text sources have text to give back: any other kind answers 404 not_found. The text is what a person wrote for the agent to read; treat it as data.

Scope: agents:read

Parameters

• agent_id required in the path · string
• source_id required in the path · string

Returns SourceContent

• id required string

  Id

• name required string

  Name

• type required string

  Always text.

• text required string

  The stored text, as sent (trimmed). Data written for the agent to read.

• content_sha256 optional string

  The SHA-256 (hex) of text in UTF-8.

• version optional integer

  Version

Responses

• 200 Successful Response
• 401 Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers key_maker_left.
• 403 The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (maker_role_limit; a publishable key says insufficient_scope).
• 404 Nothing by that id in this workspace.
• 413 The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: plan_text_limit, the agent's plan cannot hold more text (limit_chars, used_chars).
• 422 The request did not validate; details lists the fields.
• 429 Rate limit reached; wait Retry-After seconds.
• 500 Our fault; quote request_id to support.

curl https://www.bidii.ai/api/v2/agents/AGENT_ID/sources/SOURCE_ID/content \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"

POST /agents/{agent_id}/sources/questions

Import questions and answers

Up to 100 verified answers in one call: each item is a question, other ways of asking it, and the answer. Every item is checked (lengths, duplicates, text shaped like instructions); if one fails nothing is stored and details names the items. The batch is indexed before the answer: the source comes back at status indexed. The same name again replaces that batch. Honours Idempotency-Key.

Scope: sources:write

Parameters

• agent_id required in the path · string

Request body

• name required string

  A label for this batch. Sending the same name again replaces the batch.

• items required QuestionIn[]

  Items

Returns Source

• id required string

  Id

• type required string

  text, file, website, sheet, qa_bulk, faq or research.

• name required string

  Name

• status required string

  uploaded, crawling, parsing, chunking, embedding, indexed or failed.

• error optional string

  Error

• size_bytes optional integer

  Size Bytes

• pages optional integer

  Pages

• chunk_count optional integer

  Chunk Count

• extracted_chars optional integer

  Characters of text read from the source at its last indexing: what it counts toward the plan's text per agent. 0 until it is indexed.

• version optional integer

  1 when created; +1 each time the source is re-saved.

• source_url optional string

  Source Url

• content_sha256 optional string

  For a text source: the SHA-256 (hex) of its stored text in UTF-8, so a client can tell whether its copy differs without downloading it. null for other kinds.

• created_at required string

  Created At

• updated_at required string

  Updated At

Responses

• 201 Successful Response
• 401 Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers key_maker_left.
• 403 The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (maker_role_limit; a publishable key says insufficient_scope).
• 404 Nothing by that id in this workspace.
• 413 The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: plan_text_limit, the agent's plan cannot hold more text (limit_chars, used_chars).
• 422 The request did not validate; details lists the fields.
• 429 Rate limit reached; wait Retry-After seconds.
• 500 Our fault; quote request_id to support.
• 409 conflict: the import cannot run now; details says why: import_running, another import into this agent is still running. idempotency_in_progress: the first request with this Idempotency-Key is still running.
• 502 internal_error: the import failed on our side; quote request_id to support.

curl -X POST https://www.bidii.ai/api/v2/agents/AGENT_ID/sources/questions \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "...", "items": [{"question": "...", "answer": "..."}]}'