Agents

Launch background agents, poll their status, stop running work, and continue completed sessions with follow-up prompts.

Agents can run directly from a prompt, optionally with files they can read, or from a workflow template. When launching a workflow that declares file input slots, provide files through the named inputs map instead of prompt.

Launch an agent

POST /agents

Create a background agent and start it asynchronously.

Scope: developer:agent · Rate limit: Heavy (30 req / min)

Request body

Field	Type	Required	Description
prompt	{ text: string }	No	Prompt for a simple agent or workflow without file input slots.
workflowId	string (uuid)	No	Workflow template to run. Omit to launch a simple prompt-based agent.
projectId	string (uuid)	No	Project to scope the agent to.
fileIds	string[] (uuid)	No	Files and folders a simple agent can read. Not valid when workflowId is provided.
inputs	object of string arrays	No	Named file input slots for workflow agents. Keys are workflow slot names and values are IDs.

Provide either prompt.text or workflowId. For workflows with file input slots, omit prompt and provide inputs.

Response

{
  "data": {
    "id": "019abc12-3456-7890-abcd-ef1234567890",
    "status": "waiting",
    "workflowId": null,
    "projectId": "019abc12-3456-7890-abcd-ef1234567891",
    "artifacts": [],
    "files": [],
    "createdAt": "2026-04-25T12:00:00.000Z",
    "updatedAt": "2026-04-25T12:00:00.000Z"
  }
}

Errors

Status	Cause
400	Invalid body, inaccessible files, or incompatible inputs.
401	Missing or invalid API key.
403	API key lacks developer:agent scope.
404	Workflow not found or not accessible.
429	Rate limit exceeded or the user's spend limit was reached.

Example

curl -X POST "https://<your-domain>.nomic.ai/api/v0/agents" \
  -H "Authorization: Bearer $NOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": { "text": "Summarize the uploaded inspection report." },
    "fileIds": ["019abc12-3456-7890-abcd-ef1234567892"]
  }'

---

List agents

GET /agents

List background agents owned by the authenticated user.

Scope: developer:agent · Rate limit: Standard (300 req / min)

Query parameters

Parameter	Type	Description
limit	integer	Max results. Default: 20, max: 100.
cursor	string	Pagination cursor from the previous response.
status	string	Filter by waiting, running, finished, stopped, or failed.
workflowId	string (uuid) or null	Filter by workflow ID. Pass null to exclude agents launched from a workflow.

Response

{
  "data": [
    {
      "id": "019abc12-3456-7890-abcd-ef1234567890",
      "status": "running",
      "workflowId": null,
      "projectId": "019abc12-3456-7890-abcd-ef1234567891",
      "artifacts": [],
      "createdAt": "2026-04-25T12:00:00.000Z",
      "updatedAt": "2026-04-25T12:01:00.000Z"
    }
  ],
  "nextCursor": null
}

---

Get agent details

GET /agents/{id}

Get the latest status, files, and artifact references for a specific agent.

Scope: developer:agent · Rate limit: Standard (300 req / min)

Path parameters

Parameter	Type	Description
id	string (uuid)	Agent ID.

Example

curl "https://<your-domain>.nomic.ai/api/v0/agents/019abc12-3456-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer $NOMIC_API_KEY"

---

Stop an agent

POST /agents/{id}/stop

Request cancellation of a running agent. The transition is asynchronous, so poll GET /agents/{id} to observe the final stopped status.

Scope: developer:agent · Rate limit: Standard (300 req / min)

---

Follow up on an agent

POST /agents/{id}/followup

Continue a finished, stopped, or failed agent with a new user prompt.

Scope: developer:agent · Rate limit: Heavy (30 req / min)

Request body

Field	Type	Required	Description
prompt	{ text: string }	Yes	Follow-up prompt to queue.

Example

curl -X POST "https://<your-domain>.nomic.ai/api/v0/agents/019abc12-3456-7890-abcd-ef1234567890/followup" \
  -H "Authorization: Bearer $NOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": { "text": "Now turn that summary into a punch list." }
  }'