> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Resolutions API

> Get a complete AGO answer from text, a conversation, or an email without streaming

Call an AGO agent from your support system, automation, or application and receive its completed answer. AGO uses the agent's configured knowledge, tools, and conversation history.

## Before you start

Create a [scoped API key](/security/api-key-authentication) with `resolutions:write`. This scope also lets you retrieve results. Requests run as the **user who created the key**, using that user's agent and knowledge permissions. The creator must remain active. Keys without a creator cannot run resolutions. OAuth calls run as the user who granted access.

An email's `from` field supplies context only; it never changes the execution user. Configured tools can perform actions, so choose an agent whose tools match your integration's needs.

## Request an answer

```bash theme={null}
curl -X POST "https://your-tenant-id.api.useago.com/api/v1/resolutions" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/markdown" \
  -H "Idempotency-Key: support-request-123" \
  -d '{
    "agent_id": "11111111-1111-4111-8111-111111111111",
    "input": "How do I reset my password?"
  }'
```

`input` accepts the following shapes directly. No input type flag is needed.

### Text

```json theme={null}
{
  "agent_id": "11111111-1111-4111-8111-111111111111",
  "input": "How do I reset my password?"
}
```

You can also paste an email into the text input.

### Conversation

Supply messages oldest first, ending with the user message AGO should answer:

```json theme={null}
{
  "agent_id": "11111111-1111-4111-8111-111111111111",
  "input": [
    {"role": "user", "content": "I cannot log in."},
    {"role": "assistant", "content": "What error do you see?"},
    {"role": "user", "content": "Account locked."}
  ]
}
```

AGO saves the earlier messages as history and generates only the next answer. Historical messages do not execute tools. Only `user` and `assistant` roles are accepted; configure system instructions on the agent.

### Email

```json theme={null}
{
  "agent_id": "11111111-1111-4111-8111-111111111111",
  "input": {
    "subject": "Account locked",
    "from": "alice@example.com",
    "to": ["support@example.com"],
    "text": "Hello, I cannot access my account."
  }
}
```

Use `text` for the body, or `html` when plain text is unavailable. If both are supplied, AGO uses `text`. Subject, sender, and recipients are optional. AGO converts HTML into readable text without loading images or external resources. This endpoint does not send the generated reply as an email.

### Parameters and limits

| Field             | Required | Description                                                               |
| ----------------- | -------- | ------------------------------------------------------------------------- |
| `agent_id`        | Yes      | UUID of the AGO agent to run                                              |
| `input`           | Yes      | Text, message array, or email object                                      |
| `conversation_id` | No       | Continue an existing conversation owned by the execution user             |
| `language`        | No       | Language code for localized response metadata; defaults to `en`           |
| `wait_seconds`    | No       | Wait up to this many seconds for the answer; default `30`, range `0`–`60` |

Text and email bodies accept up to 100,000 characters each. Conversation arrays accept up to 100 messages and 100,000 content characters in total. Blank messages, unknown fields, and unsupported roles are rejected. Attachments and client-executed functions are not accepted.

To continue a conversation, send its `conversation_id` with **only the new text or email**. A full history array cannot be combined with `conversation_id`. Only one resolution can be active on a conversation at a time; overlapping requests return `409`.

## Responses

By default, a completed request returns `200` with JSON:

```json theme={null}
{
  "id": "22222222-2222-4222-8222-222222222222",
  "status": "completed",
  "conversation_id": "33333333-3333-4333-8333-333333333333",
  "message_id": "44444444-4444-4444-8444-444444444444",
  "content": "To reset your password, open **Settings**…",
  "sources": [],
  "error": null,
  "status_url": "/api/v1/resolutions/22222222-2222-4222-8222-222222222222"
}
```

Set `Accept: text/markdown` or `Accept: text/plain` to receive only the completed answer body. Both preserve the answer's Markdown formatting. Identifiers are returned in `X-Resolution-Id`, `X-Conversation-Id`, and `X-Message-Id` headers. `Location` contains the status URL.

### Longer requests

If the answer is not ready within `wait_seconds`, AGO returns **`202 Accepted` with JSON**, even when you requested Markdown. The work continues. Poll the `Location` URL using the same credentials:

```bash theme={null}
curl "https://your-tenant-id.api.useago.com/api/v1/resolutions/22222222-2222-4222-8222-222222222222" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: text/markdown"
```

Follow `Retry-After` (currently 2 seconds). A completed result returns `200`; pending results continue returning `202`. Set `wait_seconds: 0` to submit immediately and always use polling. Resolution requests expire after 15 minutes if still unfinished when checked. AGO does not automatically replay interrupted work, because tools may already have performed actions.

### Statuses

| Status               | Meaning                                                                                    |
| -------------------- | ------------------------------------------------------------------------------------------ |
| `queued` / `running` | Work is pending; poll again (`202`)                                                        |
| `completed`          | The complete answer is available (`200`)                                                   |
| `requires_action`    | Human handoff, approval, or another interaction is needed; inspect the conversation in AGO |
| `canceled`           | Generation was canceled (`409`)                                                            |
| `failed`             | Processing failed (`502`); `error` contains a stable code                                  |

`requires_action` returns JSON with `200` for JSON callers, or `409` for callers requesting a text body. It is not a completed answer. Empty answers are reported as `requires_action` with `no_text_answer`. Failure and cancellation responses never expose partial output as a successful answer.

## Safe retries

Send an `Idempotency-Key` header (1–255 characters) identifying the logical request. Repeating the same payload with the same key retrieves the existing resolution. Changing only `wait_seconds` or `Accept` is allowed. Reusing the key with different input, agent, language, or conversation returns `409`.

Idempotency keys and result access are scoped to the calling API key, or the OAuth application and user. Use the original credentials when retrieving a result. Do not issue a new idempotency key merely because an HTTP connection timed out: the original request may still be running.