8  Run an Agent Through the API

8.1 How the agent run API works

Use the agent run API to run one of the workspace’s agents, such as Knowledge Search, Deep Research or Presentation, from your own script or application without a chat. One request starts one agent run. Your client then checks the run until it is finished and reads the answer and any files.

Every run stands alone. It has no conversation history, and the agent cannot ask you a follow-up question. To run an agent inside a conversation instead, use the Chat API. To send a request and let Sophea pick the agents and tools, see Let Sophea pick the agents.

8.2 Get a token

Use a personal or service-account token, as described in Get a token and workspace address, and send it in the Authorization: Bearer header of every request. A token acts as its owner: an agent run reaches only the documents and agents that the owner can use.

NOUS_URL='https://nous.sophea.ai'
NOUS_TOKEN='<paste-your-token>'

8.3 List the agents

curl -sS "$NOUS_URL/api/external-agents" \
  -H "Authorization: Bearer $NOUS_TOKEN"

The response lists every agent added to the workspace. Each item includes:

Field Meaning
slug The name you use in the run address, for example nous-rag or research.
display_name The agent’s name in Nous.
description What the agent does. Use it to choose an agent.
tags Short labels for the agent.
unavailable true when the workspace cannot run this agent right now.

8.4 Start a run

Choose an operation ID for the run: 1 to 64 letters, digits, _ or -. Then send the prompt with PUT:

curl -sS -X PUT "$NOUS_URL/api/external-agents/research/operations/q3-market-2026" \
  -H "Authorization: Bearer $NOUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What changed in our Q3 sales plan, and how does it compare with the market?"}'

The body contains only prompt. A prompt can be up to 50,000 characters, or 4,000 for Knowledge Search (nous-rag).

Sending the same PUT again within 24 hours is safe: it returns the same run instead of starting a second one. A run is kept for 24 hours after it last changed; after that, the same request starts a new run. Sending a different prompt with an operation ID you already used returns HTTP 409. The same prompt can also return 409 when the token owner’s document access changed after the run started, for example after a new upload; GET still returns the run. Use a new operation ID for every new request.

Each person can have ten named-agent runs in progress at a time. A PUT that would start an eleventh returns HTTP 429 with a Retry-After header that says how many seconds to wait; send the same PUT again after that. Repeating the PUT of a run that already exists is never refused.

8.5 Check the run and read the answer

Read the run with GET on the same address:

curl -sS "$NOUS_URL/api/external-agents/research/operations/q3-market-2026" \
  -H "Authorization: Bearer $NOUS_TOKEN"

PUT and GET return the same fields:

Field Meaning
status pending or running while the agent works; completed, failed or cancelled when the run is finished.
final_text The agent’s answer, once the run is finished; null while it runs.
artifacts Files the agent produced, once the run is finished.
sources The sources the answer cites, once the run is finished. n is the number the answer uses, such as [1]; kind is web, document (a workspace document) or record (an entry from an agent’s own collection, such as a law or a tender); title and url name the source; a workspace document also has its source_type, such as file.
notice A code and params that explain a limit the run met, such as used-up workspace credits, or null.
created_at, updated_at, completed_at When the run started, last changed and finished.

While the run is not finished, check again every few seconds. Deep Research takes a few minutes. Also send the same PUT again about every 30 seconds: if the worker running the agent stopped, this starts the run again.

8.6 Download files

Each item in artifacts has an artifact_id and a download_url, and, when known, filename, content_type, size_bytes and sha256. Download a file with the same token:

curl -sS -o slides.pptx "$NOUS_URL<download_url>" \
  -H "Authorization: Bearer $NOUS_TOKEN"

GET .../operations/<operation_id>/artifacts lists the files again. A download can be up to 100 MiB.

8.7 Cancel a run

curl -sS -X DELETE "$NOUS_URL/api/external-agents/research/operations/q3-market-2026" \
  -H "Authorization: Bearer $NOUS_TOKEN"

The run ends with status cancelled. Cancelling a run that has already finished changes nothing.

8.8 Get everything in one answer

The agent cannot ask you a question during an API run. When it needs more detail, for example which chart to put into a presentation, its finished answer says what is missing. Send a new run with a new operation ID and include everything in the prompt.

Knowledge Search and Deep Research search the workspace documents the token owner can read, including the owner’s own uploads. Deep Research also searches the web and lists both kinds of source in sources. If a Deep Research report cites a workspace document the token owner can no longer read, the run is returned as failed with the message “The report could not be completed. Try again.”

8.9 Let Sophea pick the agents

When you do not know which agent fits, send the request without naming one. Sophea answers it the way the default agent answers in chat: it can search the workspace documents the token owner can read, search the web, and run any agent switched on for the workspace. Only agents switched on for the workspace are used.

curl -sS -X PUT "$NOUS_URL/api/external-agents/operations/leave-policy-2026" \
  -H "Authorization: Bearer $NOUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Summarise our leave policy and make a short presentation about it."}'

The operation ID follows the same rules as above, except that operations cannot be used. The body contains only prompt, up to 50,000 characters. Check the run with GET and cancel it with DELETE on the same address. Repeating the same PUT is safe and returns the same run; a different prompt with the same operation ID returns HTTP 409. A run is kept for 24 hours.

The response has these fields:

Field Meaning
status running while Sophea works; completed, failed or cancelled when the run is finished.
final_text Sophea’s answer, once the run is completed. A marker such as [[1]](https://...) refers to the item with the same n in sources.
sources The sources the answer cites, with n, kind (web or document), title, url and, for a workspace document, source_type.
steps Each agent or tool the run used, in order: kind (agent or tool), name, status (completed, partial, failed or cancelled) and notice. An agent step also has the agent’s own answer in text and that answer’s own sources; its numbers refer to that text, not to final_text.
artifacts Files the agents produced. Download each from its download_url with the same token.
notice Why a run failed, or null: run_interrupted (the server running it stopped; send the same PUT again to restart it), workspace_credits_exhausted (with renews_on) or run_failed. A failed run is returned as it is for the same operation ID; to try again, use a new operation ID.
created_at, updated_at, completed_at When the run started, last changed and finished.

Each person can have ten of these runs in progress at a time, apart from the ten named-agent runs. An eleventh, or a run sent while the server is busy, returns HTTP 429 with a Retry-After header that says how many seconds to wait. Sophea cannot ask you a question during the run: when it needs more detail, its answer says what is missing. A run has no overall time limit of its own; one that uses Deep Research or several agents can take several minutes.

8.10 If something does not work

HTTP status What it means
401 The token is missing, wrong or expired.
403 The request names a different workspace than the token belongs to.
404 The agent or the operation does not exist, or the agent is not available to the workspace.
409 The operation ID was already used with a different prompt, or the token owner’s document access changed after the run started. Use a new operation ID; GET still returns the earlier run. When Sophea picks the agents, 409 can also mean the default agent is switched off in the workspace.
413 The file is larger than 100 MiB.
422 The request is invalid: check the operation ID, that the body has only a non-empty prompt, and the prompt length.
429 Too many runs are in progress. Wait the number of seconds in Retry-After, then send the same PUT again.
503 The run is finished, but its sources could not be checked right now. Send the GET again shortly.
502 or 504 The agent service did not answer in time or could not be reached. Send the same PUT again later; within 24 hours it does not start a second run.