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 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

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

{
  "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:

{
  "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

{
  "agent_id": "11111111-1111-4111-8111-111111111111",
  "input": {
    "subject": "Account locked",
    "from": "[e-mail]",
    "to": ["[e-mail]"],
    "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:

{
  "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:

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.