> ## Documentation Index > Fetch the complete documentation index at: https://developers.harvey.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Agent Thread > Creates a thread that runs the agent on a prompt, optionally with documents to read, and returns immediately with a thread id. The agent runs asynchronously. [Get agent thread](/api-reference/agents/get-agent-thread) for the answer. ### Permissions Requires `Agents and workflows API` and `Use agents and workflows` permissions. If these permissions are not available to select, contact [support@harvey.ai](mailto:support@harvey.ai). ## OpenAPI ````yaml /agents_api.json post /api/v1/agent_threads openapi: 3.0.1 info: title: Harvey Agents API description: >- Run Harvey text-based agents programmatically. Discover the agents available to your workspace, start an agent on a prompt with optional documents, then poll for the answer, its citations, and any files the agent produced. version: 1.0.0 contact: email: support@harvey.ai servers: - url: https://api.harvey.ai description: Harvey API server security: [] paths: /api/v1/agent_threads: post: tags: - Agents summary: Create Agent Thread description: >- Creates a thread that runs the agent on a prompt, optionally with documents to read, and returns immediately with a thread id. The agent runs asynchronously. [Get agent thread](/api-reference/agents/get-agent-thread) for the answer. operationId: createAgentThread requestBody: required: true content: multipart/form-data: schema: type: object required: - agent_id - prompt properties: agent_id: type: string format: uuid description: The agent to run in the new thread. example: 01a0d9c9-3334-7036-ad4a-d14db13b93ba prompt: type: string minLength: 1 maxLength: 4000 description: The instruction for the agent to execute. example: >- Summarize the termination rights in this agreement. For each, state who may exercise it, the notice period, and any cure period. client_matter_id: type: string minLength: 1 maxLength: 128 description: >- Client matter to attribute the work to. Accepts either the matter's `id` or `name`. Required if your workspace requires a client matter on every query. example: 2024-0147 files: type: array description: >- A document for the agent to read. Repeat the field once per document. Up to 50 files, 100 MB per file and 100 MB across the whole request. A file whose type or size is not accepted refuses the entire request. items: type: string format: binary responses: '202': description: Thread created. content: application/json: schema: $ref: '#/components/schemas/AgentThread' examples: createAgentThread: summary: Example response for creating a thread value: id: 1671319 status: IN_PROGRESS agent_id: null client_matter_id: 4f21c0b8-9d3e-4a77-8c21-6b0e5d9a1f34 harvey_url: https://app.harvey.ai/assistant/assist/1671319 created_at: '2026-10-09T05:12:59.454218Z' output: null error: null files: - name: northwind-msa.pdf processing_status: UPLOADED failure_category: null error: null '400': description: Bad Request - The request was rejected before the thread was created content: application/json: schema: $ref: '#/components/schemas/AgentThreadError' examples: invalidAgentId: summary: agent_id is not a valid UUID value: error: code: INVALID_AGENT_ID message: Invalid agent id. kind: unprocessable_content status_code: 400 invalidRequestBody: summary: A missing, misspelled or unrecognized form field value: error: code: INVALID_REQUEST_BODY message: 'Invalid request body. prompt: This field is required' kind: unprocessable_content status_code: 400 fileRejected: summary: A document's type or size is not accepted value: error: code: FILE_REJECTED message: >- Upload failed. File northwind-msa.zip exceeds maximum size of 100MB. kind: unprocessable_content status_code: 400 runRefused: summary: A required client matter was omitted or does not resolve value: error: code: RUN_REFUSED message: >- A client matter is required for every query in this workspace. kind: unprocessable_content status_code: 400 '401': description: Unauthorized - Invalid or missing API token, or a missing permission '403': description: Forbidden - The client matter is blocked by an ethical wall policy '404': description: >- Not Found - No agent you can run has this `agent_id`, or the Agents API is not enabled for your workspace '415': description: >- Unsupported Media Type - The request body was not `multipart/form-data` content: application/json: schema: $ref: '#/components/schemas/AgentThreadError' examples: unsupportedMediaType: summary: A JSON body was sent instead of multipart/form-data value: error: code: UNSUPPORTED_MEDIA_TYPE message: Agent threads accept a multipart/form-data body. kind: unprocessable_content status_code: 415 '429': description: Too Many Requests - Rate limit exceeded '500': description: >- Internal Server Error - The thread could not be created. Safe to retry security: - bearerAuth: [] components: schemas: AgentThread: type: object description: A thread and the agent run it holds. properties: id: type: integer description: The unique identifier of the agent thread. status: $ref: '#/components/schemas/AgentThreadStatus' agent_id: type: string format: uuid nullable: true description: The agent this thread ran. Null until the agent begins executing. client_matter_id: type: string format: uuid nullable: true description: >- The client matter this thread is attributed to, as a UUID, even if you supplied a name. Null when none was supplied. harvey_url: type: string format: uri description: >- Link to the thread in the Harvey web app, for handing the work to a person. created_at: type: string format: date-time description: When the thread was created. output: type: object nullable: true allOf: - $ref: '#/components/schemas/AgentThreadOutput' description: >- What the agent produced. Null until `status` is terminal, and on a thread that produced no answer. error: type: string nullable: true description: >- Why the thread did not complete. Null unless `status` is `ERRORED` or `CANCELLED`. files: type: array description: >- The documents you attached, each with the processing status recorded for it. Generated files live under `output.files` instead. items: $ref: '#/components/schemas/AgentThreadInputFile' AgentThreadError: type: object description: >- Returned when `POST /api/v1/agent_threads` rejects a request before the thread is created. properties: error: type: object description: What was wrong with the request. properties: code: type: string description: >- Machine-parseable reason the request was rejected. Switch on this value rather than parsing `message`, which is localized and may change. enum: - FILE_REJECTED - INVALID_AGENT_ID - INVALID_REQUEST_BODY - RUN_REFUSED - UNSUPPORTED_MEDIA_TYPE message: type: string description: >- A readable explanation of the failure. For `INVALID_REQUEST_BODY` it also names the fields at fault. kind: type: string description: >- Error family. Always `unprocessable_content` on this endpoint, including for the `415`. enum: - unprocessable_content status_code: type: integer description: HTTP status code echoed in the body. AgentThreadStatus: type: string description: >- Lifecycle state of a thread. `COMPLETED`, `ERRORED` and `CANCELLED` are terminal. enum: - PENDING - IN_PROGRESS - COMPLETED - ERRORED - CANCELLED AgentThreadOutput: type: object description: What a finished thread produced. properties: text: type: string description: >- The agent's answer, with each source rendered as a `[N]` marker that matches a `citation_number` in `citations`. citations: type: array description: >- Sources behind the answer, ordered by where their marker first appears in `text`. A source the answer never marked up sorts after those, keeping its `citation_number` null. items: $ref: '#/components/schemas/AgentThreadCitation' files: type: array description: Files the agent generated, in the order it produced them. items: $ref: '#/components/schemas/AgentThreadGeneratedFile' AgentThreadInputFile: type: object description: A document you attached. properties: name: type: string description: The file name as you uploaded it. processing_status: type: string description: >- Where the file is in processing. The agent can read it at `READY_TO_QUERY`, and is still waiting on it at `UPLOADED` or `PROCESSING`. enum: - UPLOADED - PROCESSING - READY_TO_QUERY - READY_TO_REVIEW - RECOVERABLE_FAILURE - UNRECOVERABLE_FAILURE failure_category: type: string nullable: true description: >- Why the file failed, or null if it did not. This is the verdict — check it rather than `processing_status`, which can report a success state for a file that still failed. enum: - UNSUPPORTED_FILE_TYPE - FILE_SIZE_TOO_LARGE - EMPTY_DOCUMENT - FILE_TYPE_MISMATCH - PASSWORD_PROTECTED - CERTIFICATE_ENCRYPTED - OCR_ERROR - DOCUMENT_TOO_LARGE - UPLOAD_NO_FILENAME - UPLOAD_FILE_TOO_LARGE - UPLOAD_INVALID_FILE_TYPE - UPLOAD_PATH_TOO_LONG - OTHER_UPLOAD_ERROR - RECOVERABLE_ERROR - INTERNAL_ERROR - DMS_DOWNLOAD_ERROR - UNKNOWN - DMS_SYNC_VALIDATION_UNKNOWN - FILE_CORRUPTED - IMG_NO_TEXT - CANNOT_PROCESS_FILE - OCR_PROCESSING_LIMIT - null error: type: string nullable: true description: A readable message for the failure. Null when the file did not fail. AgentThreadCitation: type: object description: >- One source behind the answer, keyed to its `[N]` marker in the answer text. Every field is nullable, because a source carries only what its material can supply — a web result has no page, for example. properties: citation_number: type: integer nullable: true description: >- The `[N]` marker this source appears as in `output.text`. Null when the answer text never marked this source up. file_id: type: string format: uuid nullable: true description: >- Identifier of the source document. Null when the source is not a document in Harvey. file_name: type: string nullable: true description: >- Name of the source document. Null when the source is not a document in Harvey. citation_page: type: integer nullable: true description: >- The page number printed on the document, counting from 1. Null when the source has no pages. citation_quote: type: string nullable: true description: >- The quoted passage. `` wraps the quoted span inside its surrounding context. Null when the source carries no quotable passage. AgentThreadGeneratedFile: type: object description: A file the agent produced. properties: file_id: type: string format: uuid description: >- Identifier of the generated file. Pass this to `POST /api/v1/files/download` to fetch the bytes. file_name: type: string nullable: true description: >- The file name the agent gave the document. Null when the agent produced the file without naming it. content_type: type: string nullable: true description: >- MIME type of the file, such as `application/vnd.openxmlformats-officedocument.wordprocessingml.document`. Null when the type was not recorded; read it from the download response instead. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Token ```` ## Related topics - [Rate Limits](/api-reference/ratelimits.md) - [Get Agent Thread](/api-reference/agents/get-agent-thread.md) - [Agents](/guides/agents.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.