Management API

Manage the lifecycle of your agents. All endpoints require an API key issued from the Account → API Keys page.

To create a new agent, see the Create Agent API page.

Quick Start

curl -H "Authorization: Bearer <api-key>" \
  "https://api.uragents.ai/v1/agents"

Use this request to confirm your API key works before creating or updating agents.

Authentication

Include your API key in every request:

Authorization: Bearer <your-api-key>

Alternatively, you can use the X-Api-Key header.

List Agents

GET /v1/agents

Returns all non-deleted agents belonging to your account, newest first.

Query params (optional):

Response:

{
  "data": [
    {
      "id": "agent-123",
      "name": "Price Monitor",
      "baseUrl": "https://<website-url>",
      "status": "ACTIVE",
      "schedule": "{\"tasksPerDay\":1,\"times\":[\"09:00\"]}",
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:00:00.000Z"
    }
  ],
  "nextToken": null
}

Get Agent

GET /v1/agents/{agentId}

Response: 200 OK — single agent object as shown above.
Returns 404 if the agent doesn’t exist or isn’t owned by your API key.

Update Agent

PATCH /v1/agents/{agentId}

Update one or more agent fields. All fields are optional — include only the ones you want to change.

Body:

{
  "name": "New title",
  "content": "Updated context / task instructions",
  "schedule": "{\"tasksPerDay\":2,\"times\":[\"09:00\",\"18:00\"]}",
  "baseUrl": "https://<website-url>"
}

Response: 200 OK — updated agent object.

Pause Agent

POST /v1/agents/{agentId}/pause

Sets the agent status to PAUSED and removes its EventBridge schedule so no further automatic runs fire.

Response: 200 OK — updated agent object with status: "PAUSED".

Delete Agent

DELETE /v1/agents/{agentId}

Soft-deletes the agent (status = DELETED) and removes its schedule. Deleted agents no longer appear in list or get responses.

Response:

{ "data": { "message": "Agent deleted successfully" } }