# Caitlyn developer docs

> The Caitlyn v3 API and its SDKs for TypeScript, Python, Go and Rust: how to sign in, call the API, handle
> errors, retries, streams and pages, and the reference for every operation, type and error code. Every page
> is also Markdown, at its address with `.md` in place of the trailing slash.

## Start here

- [Caitlyn developer docs](https://build.caitlyn.ai/index.md): Build on Caitlyn from your own code: ask an agent a question and stream its cited answer, load documents into a knowledge base, and change an agent safely, through the Caitlyn v3 API and its SDKs…
- [Getting started](https://build.caitlyn.ai/getting-started.md): Install an SDK, create a client for your workspace, and read an agent's draft.
- [Authentication](https://build.caitlyn.ai/authentication.md): A client signs in one of six ways, chosen by its auth option. Every way except token and session ends in the same thing: a short-lived Caitlyn access token, which the client caches, renews before…
- [Errors](https://build.caitlyn.ai/errors.md): Every error the API returns is an RFC 9457 problem details object, and every SDK raises it as a typed error you can tell apart by HTTP status and by code.
- [Retries](https://build.caitlyn.ai/retries.md): The SDKs retry a failed call for you, but only when that is safe and only when trying again might help. Every SDK follows the same rules.
- [Streaming](https://build.caitlyn.ai/streaming.md): An agent's answer arrives as it is written, as a stream of typed events. SendMessage returns one; each SDK gives you something to iterate, and the finished message at the end.
- [Pagination](https://build.caitlyn.ai/pagination.md): A list operation returns its results a page at a time. The SDKs hide the pages: iterate the result and each page is fetched when the loop reaches it, so a break stops fetching.
- [Telemetry](https://build.caitlyn.ai/telemetry.md): Every SDK records each call as OpenTelemetry spans, with the same names and attributes in every language, so a trace looks the same whichever SDK made it. TypeScript, Python and Go use the…

## Guides

- [Sign in from a browser](https://build.caitlyn.ai/guides/sign-in-from-a-browser.md): Anyone can read the code a browser runs, and any script that runs on your page can read what that code holds. So a browser app never holds a client secret or a long-lived token. There are two ways…

## API reference

- [ResumeConversationStream](https://build.caitlyn.ai/reference/resume-conversation-stream.md): Re-attaches to the answer that is being written, from the event after Last-Event-ID.
- [SendMessage](https://build.caitlyn.ai/reference/send-message.md): Sends a message and streams the answer as server-sent events.
- [CreateDocument](https://build.caitlyn.ai/reference/create-document.md): Creates a document from an upload; ingestion continues after the response.
- [ListDocuments](https://build.caitlyn.ai/reference/list-documents.md): Lists the documents in a knowledge base, one page at a time.
- [CreateUpload](https://build.caitlyn.ai/reference/create-upload.md): Reserves a short-lived slot for a file's bytes and returns a presigned URL bound to their checksum.
- [GetAgentVersion](https://build.caitlyn.ai/reference/get-agent-version.md): Gets one version of an agent, with its full configuration and its ETag.
- [UpdateDraftVersion](https://build.caitlyn.ai/reference/update-draft-version.md): Edits the draft with a partial update of its configuration; If-Match is required.

## Types

- [AgentConfiguration](https://build.caitlyn.ai/reference/types/agent-configuration.md): An agent version's configuration.
- [AttachmentSettings](https://build.caitlyn.ai/reference/types/attachment-settings.md): Chat attachment settings.
- [Citation](https://build.caitlyn.ai/reference/types/citation.md): A passage the answer cites.
- [CitationAdded](https://build.caitlyn.ai/reference/types/citation-added.md): The data of citation.added.
- [ClearableDraftField](https://build.caitlyn.ai/reference/types/clearable-draft-field.md): The draft members that can be cleared. Open: an older SDK may send a newer value as a string.
- [ContentSafety](https://build.caitlyn.ai/reference/types/content-safety.md): The content safety setting on a version.
- [ContextItem](https://build.caitlyn.ai/reference/types/context-item.md): One item of structured context, for example the page or record the person is looking at.
- [ConversationEvent](https://build.caitlyn.ai/reference/types/conversation-event.md): The events on a conversation's answer stream. The SSE event: name is each member's @jsonName. Clients skip event names they do not know.
- [Document](https://build.caitlyn.ai/reference/types/document.md): One document in a knowledge base, stable across new uploads of new bytes.
- [DocumentStatus](https://build.caitlyn.ai/reference/types/document-status.md): Where a document is in its lifecycle. Open: new values may be added. indexed, partiallyindexed and failed are final.
- [FieldError](https://build.caitlyn.ai/reference/types/field-error.md): One problem with one request member or query parameter.
- [InputRequested](https://build.caitlyn.ai/reference/types/input-requested.md): The data of input.requested.
- [KnowledgeBaseBinding](https://build.caitlyn.ai/reference/types/knowledge-base-binding.md): One knowledge base an agent searches, and how.
- [Message](https://build.caitlyn.ai/reference/types/message.md): A message in a conversation.
- [MessageCompleted](https://build.caitlyn.ai/reference/types/message-completed.md): The data of message.completed.
- [MessageFailed](https://build.caitlyn.ai/reference/types/message-failed.md): The data of message.failed: a problem details object, exactly as an error response body.
- [MessageRole](https://build.caitlyn.ai/reference/types/message-role.md): Who wrote a message. Open: new values may be added.
- [MessageStarted](https://build.caitlyn.ai/reference/types/message-started.md): The data of message.started.
- [Operation](https://build.caitlyn.ai/reference/types/operation.md): Background work that continues after the request that started it. Read it, wait on it or watch it; never start the work again to find out how it went.
- [OperationKind](https://build.caitlyn.ai/reference/types/operation-kind.md): What kind of work an Operation is. Open: one value per kind of work, added as kinds are modelled.
- [OperationStatus](https://build.caitlyn.ai/reference/types/operation-status.md): Where an Operation is. Open: new values may be added. succeeded, succeededwithfailures, failed and cancelled are final.
- [PartialFailure](https://build.caitlyn.ai/reference/types/partial-failure.md): An enrichment that did not complete. It never fails the document.
- [PhaseChanged](https://build.caitlyn.ai/reference/types/phase-changed.md): The data of phase.changed.
- [ProgressStatus](https://build.caitlyn.ai/reference/types/progress-status.md): A progress step's status. Open: new values may be added. succeeded and failed are final.
- [ProgressUpdated](https://build.caitlyn.ai/reference/types/progress-updated.md): The data of progress.updated.
- [TextDelta](https://build.caitlyn.ai/reference/types/text-delta.md): The data of text.delta.
- [ToolFinished](https://build.caitlyn.ai/reference/types/tool-finished.md): The data of tool.finished.
- [ToolStarted](https://build.caitlyn.ai/reference/types/tool-started.md): The data of tool.started.
- [ToolStatus](https://build.caitlyn.ai/reference/types/tool-status.md): How a tool call ended. Open: new values may be added. Every value is final.
- [UploadStatus](https://build.caitlyn.ai/reference/types/upload-status.md): Where an upload is in its lifecycle. Open: new values may be added. consumed and expired are final.
- [VersionSource](https://build.caitlyn.ai/reference/types/version-source.md): How a version was made. Open: new values may be added.

## Optional

- [VALIDATION_FAILED](https://build.caitlyn.ai/errors/VALIDATION_FAILED.md): The request is malformed: a member is missing, has the wrong type or is out of range. On an update, it is also what a member that is both set and named in clear, or a clear entry that cannot be…
- [UNKNOWN_FIELD](https://build.caitlyn.ai/errors/UNKNOWN_FIELD.md): The request has a member the operation does not define. v3 refuses unknown members rather than ignoring them, so a misspelt member is never silently dropped.
- [UNKNOWN_FILTER](https://build.caitlyn.ai/errors/UNKNOWN_FILTER.md): A list request has a filter, or a filter operator, the operation does not declare.
- [UNKNOWN_SORT](https://build.caitlyn.ai/errors/UNKNOWN_SORT.md): A list request asks to sort by a field the operation cannot sort by.
- [INVALID_CURSOR](https://build.caitlyn.ai/errors/INVALID_CURSOR.md): The cursor is not one this list returned, or it belongs to a different list or different filters.
- [UNAUTHENTICATED](https://build.caitlyn.ai/errors/UNAUTHENTICATED.md): No credential was sent, or it has expired or is not valid.
- [PERMISSION_DENIED](https://build.caitlyn.ai/errors/PERMISSION_DENIED.md): The caller does not have the permission the operation needs, or its kind of credential may not call the operation (some operations are for people only, or not for guests).
- [NOT_AVAILABLE_TO_CREDENTIALS](https://build.caitlyn.ai/errors/NOT_AVAILABLE_TO_CREDENTIALS.md): The operation issues or revokes credentials, so no token may call it: its permission belongs to no scope. A credential that could create credentials would escape its own revocation.
- [PRIMARY_WORKSPACE_REQUIRED](https://build.caitlyn.ai/errors/PRIMARY_WORKSPACE_REQUIRED.md): The operation acts on the whole organisation, and only the organisation's primary workspace serves it.
- [NOT_FOUND](https://build.caitlyn.ai/errors/NOT_FOUND.md): The record does not exist, or the caller may not see it. The two are deliberately the same, so identifiers cannot be probed. For an agent version, it is also what someone without the agent's…
- [CONFLICT](https://build.caitlyn.ai/errors/CONFLICT.md): The resource's current state does not allow the request: for example, an upload that has already been used, or a message sent while an answer to the previous one is still being written.
- [ALREADY_EXISTS](https://build.caitlyn.ai/errors/ALREADY_EXISTS.md): A name that must be unique is already taken.
- [IDEMPOTENCY_KEY_IN_USE](https://build.caitlyn.ai/errors/IDEMPOTENCY_KEY_IN_USE.md): A request with the same Idempotency-Key is still being processed.
- [OPERATION_NOT_CANCELLABLE](https://build.caitlyn.ai/errors/OPERATION_NOT_CANCELLABLE.md): Cancelling an Operation (a long-running task, such as a document ingestion) that cannot be cancelled.
- [PRECONDITION_FAILED](https://build.caitlyn.ai/errors/PRECONDITION_FAILED.md): If-Match does not match the resource's current ETag: someone changed it after you read it.
- [PAYLOAD_TOO_LARGE](https://build.caitlyn.ai/errors/PAYLOAD_TOO_LARGE.md): The body, a file or the context of a sent message is over its documented limit.
- [IDEMPOTENCY_KEY_REUSED](https://build.caitlyn.ai/errors/IDEMPOTENCY_KEY_REUSED.md): The Idempotency-Key was already used with a different request body.
- [PRECONDITION_REQUIRED](https://build.caitlyn.ai/errors/PRECONDITION_REQUIRED.md): The update sent no If-Match header.
- [RATE_LIMITED](https://build.caitlyn.ai/errors/RATE_LIMITED.md): Too many requests.
- [INTERNAL](https://build.caitlyn.ai/errors/INTERNAL.md): An unexpected failure in Caitlyn.
- [SERVICE_UNAVAILABLE](https://build.caitlyn.ai/errors/SERVICE_UNAVAILABLE.md): A service Caitlyn depends on is briefly unavailable, or the request's audit event could not be recorded (Caitlyn refuses a write it cannot audit).
- [Everything in one file](https://build.caitlyn.ai/llms-full.txt): every page above, in this order