> ## Documentation Index
> Fetch the complete documentation index at: https://www.fluenterp.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Upload files, create an asynchronous run, and retrieve its documents.

An agent run is a durable, asynchronous record. Keep the returned `run_id` with your source record so you can correlate status, documents, webhooks, and support traces later.

## Run lifecycle

1. Call `GET /api/v1/agents` and select an accessible agent.
2. If the run has files, call `POST /api/v1/agents/{agent_id}/upload-urls`.
3. Upload each file directly to its presigned URL with `PUT` and the requested content type.
4. Call `POST /api/v1/agents/{agent_id}/run` with the uploaded file keys and/or a `user_message`.
5. Poll `GET /api/v1/runs/{id}` until the status is terminal, or receive a run webhook.

Run statuses are `queued`, `running`, `completed`, `failed`, and `cancelled`.

<Note>
  `completed` means the agent finished. A returned document can still be a draft, awaiting approval, or waiting to be processed into a connected system.
</Note>

## Upload a file

First request an upload URL:

```bash theme={null}
curl -X POST "https://www.fluenterp.com/api/v1/agents/$AGENT_ID/upload-urls" \
  -H "Authorization: Bearer $FLUENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {"file_name": "invoice.pdf", "content_type": "application/pdf"}
    ]
  }'
```

Upload the file with the returned `upload_url`. The URL expires after one hour:

```bash theme={null}
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @invoice.pdf
```

## Create and follow the run

```bash theme={null}
curl -X POST "https://www.fluenterp.com/api/v1/agents/$AGENT_ID/run" \
  -H "Authorization: Bearer $FLUENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"files\": [{
      \"file_key\": \"$FILE_KEY\",
      \"file_name\": \"invoice.pdf\",
      \"content_type\": \"application/pdf\"
    }],
    \"process_together\": false
  }"
```

Poll the returned `status_url` until the run is terminal. A failed run can still contain conversations and documents; inspect both the run's `error` and each document's `error`.

## Multiple and background files

* A run accepts up to 50 foreground files.
* `process_together: true` sends up to 10 foreground files through one agent conversation.
* Background files are available to tools but are not read by the agent directly. When a run contains only background files, include a `user_message` that tells the agent what to do.
* Set `notification_email` only when email notification is desired. Omitting it sends no completion email.

## Process a document

`GET /api/v1/documents/{id}` returns the full `document_data`. `POST` to the same resource processes its current data into the configured system of record. Check the returned document status: an external-system rejection is represented by `status: "error"` and an `error` message in an HTTP 200 response.

`DELETE /api/v1/documents/{id}` is a soft delete. It cancels in-flight work and moves the document to trash.