> For the complete documentation index, see [llms.txt](https://docs.ai.insly.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ai.insly.com/nora/agentic-workflows/build-an-agent/agent-endpoints.md).

# Agent endpoints

Three endpoints for agents that are running a step. They are for [agent developers](https://docs.ai.insly.com/nora/agentic-workflows/build-an-agent.md) only. API clients can't use them.

All three use the step's `callbackToken` from the envelope:

```
Authorization: Bearer <callbackToken>
```

A token belongs to one step (`agentRunId`), on one conversation, in one organisation. It is valid for the agent's configured timeout. The file endpoints work only while that step is still running.

Base URL: `https://main.formflow-dev.net`

### Send a completion or progress update

`POST /api/studio/webhooks/agent-communication`

Use this after you have [acknowledged](https://docs.ai.insly.com/nora/agentic-workflows/build-an-agent.md#answering-right-away-or-later) a step, to finish it or to tell the customer how it is going.

**Completion.** The body is the same JSON as an immediate answer:

```json
{
  "type": "completion",
  "agentRunId": "7b8c9d0e-…",
  "isComplete": true,
  "outputPayload": { "quoteReference": "Q-10442" },
  "outputMessage": "Your quote Q-10442 is ready."
}
```

**Progress.** A short status note for the customer. The step keeps running:

```json
{
  "type": "progress",
  "agentRunId": "7b8c9d0e-…",
  "isComplete": false,
  "message": "Rating 14 vehicles, this takes about a minute."
}
```

* `isComplete` is required on both types and must be `false` on progress. A progress update with `isComplete: true` fails the step.
* Progress notes are shown in the chat. They are not emailed, because an email conversation gets only the final reply.
* At most 5 progress notes per step, each up to 500 characters. Notes past the limit are ignored.

**Response.** Every valid request receives the same reply, whatever the state of the run:

```
202 { "status": "accepted" }
```

This is so the reply never reveals whether a run exists. A completion for a step that has already finished or timed out is ignored.

* `400`: the body is malformed, for example a missing `isComplete`, an unknown `type`, or an `agentRunId` that is not a UUID.
* `401`: the token is missing or invalid, or it belongs to a different `agentRunId` than the one in the body.
* Request bodies can be up to 1 MB.

### Download a file

`GET /api/studio/agent-files/{fileId}`

Swap a `fileId` from the envelope's `attachments` for the file itself. The response is a `302` redirect to a download link that is valid for 5 minutes, so follow the redirect, or read the `Location` header.

You can download:

* any file in the envelope's `attachments` (the conversation's documents), and
* the files of a submission created in the same conversation, for example after an earlier step passed you a `submissionId`.

A missing or invalid token returns `401`. Every other refusal returns `404`, including an unknown id, a file from another conversation, an upload that never finished, and a step that is no longer running.

```bash
curl -L -H "Authorization: Bearer $CALLBACK_TOKEN" \
  "https://main.formflow-dev.net/api/studio/agent-files/$FILE_ID" -o document.pdf
```

{% hint style="info" %}
Don't send the `Authorization` header to the storage URL you are redirected to. The link is already signed. Most HTTP clients, `curl -L` included, drop the header on a cross-host redirect.
{% endhint %}

### Attach a document you generated

`POST /api/studio/agent-files`

Add a document your agent created, such as a quote PDF or a bordereau, to the conversation. It appears with the conversation's files in the Nora web app. On email, it is attached to the run's final reply, if the run finishes with an answer. A run that fails, or that stops to ask for missing fields, sends no attachments.

```json
{
  "filename": "quote-Q-10442.pdf",
  "content": "JVBERi0xLjcKJeLjz9MK…",
  "caption": "Here is your quote."
}
```

<table><thead><tr><th width="120">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>filename</code></td><td>Required, up to 255 characters, stored as at most 200. The extension sets the file type, which must be one of <code>pdf</code>, <code>doc</code>, <code>docx</code>, <code>xls</code>, <code>xlsx</code>, <code>csv</code>, <code>jpg</code>, <code>jpeg</code>, <code>png</code>, <code>gif</code>, <code>heic</code>.</td></tr><tr><td><code>content</code></td><td>Required. The file's bytes, base64-encoded. Up to 10 MB before encoding.</td></tr><tr><td><code>caption</code></td><td>Optional, up to 500 characters. The text shown with the document in the conversation. Write it in the conversation's language.</td></tr></tbody></table>

**Response**

```json
{ "fileId": "c3e4f5a6-…", "filename": "quote-Q-10442.pdf", "size": 48211 }
```

The document is always stored on the step's own conversation. You can't choose another one.

Errors: `400` for a type that isn't allowed, empty content, or content over 10 MB. `401` for a missing or invalid token. `404` if the step is no longer running.

Limits for the final email: at most 5 generated documents and 15 MB in total. Documents over the limit stay in the conversation but are not attached to the email.
