Agents API

Agents are first-class principals in Patina. Each agent belongs to a workspace, has a role (viewer, editor, or owner), and authenticates with its own API key. Agents are sponsored by a human user — if the sponsor leaves the workspace, their agents are deactivated.

Only human users can manage agents. All endpoints on this page require authentication with a user API key (not an agent key). Agents cannot create, list, or modify other agents.

Endpoints

POST /agents — Register an agent
GET /agents — List agents
GET /agents/:id — Get agent details
PUT /agents/:id — Update an agent
DELETE /agents/:id — Deactivate an agent
POST /agents/:id/keys — Create an agent key
GET /agents/:id/keys — List agent keys
DELETE /agents/:id/keys/:keyId — Revoke a key

All paths are relative to /api/v1/workspaces/{workspaceId}

Register an agent

POST /agents

Creates a new agent in the workspace. The agent gets a workspace membership with the specified role, capped by the creating user's role.

Request body

Field	Type	Required	Description
`name`	string	Yes	Agent name (e.g. "claude-code", "deploy-bot")
`description`	string	No	What this agent does
`role`	string	No	`viewer` (default), `editor`, or `owner`

curl -X POST https://patina.so/api/v1/workspaces/WORKSPACE_ID/agents \
  -H "Authorization: Bearer pk_YOUR_USER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "claude-code",
    "description": "Development assistant for the engineering team",
    "role": "editor"
  }'

{
  "id": "agt_abc123...",
  "name": "claude-code",
  "description": "Development assistant for the engineering team",
  "role": "editor",
  "sponsorUserId": "user_xyz...",
  "workspaceId": "ws_def...",
  "createdAt": "2025-03-15T10:00:00.000Z"
}

List agents

GET /agents

Returns all agents in the workspace.

curl https://patina.so/api/v1/workspaces/WORKSPACE_ID/agents \
  -H "Authorization: Bearer pk_YOUR_USER_KEY"

Get agent details

GET /agents/:agentId

Returns agent details including key count.

curl https://patina.so/api/v1/workspaces/WORKSPACE_ID/agents/AGENT_ID \
  -H "Authorization: Bearer pk_YOUR_USER_KEY"

Update an agent

PUT /agents/:agentId

Updates agent name, description, or sponsor.

curl -X PUT https://patina.so/api/v1/workspaces/WORKSPACE_ID/agents/AGENT_ID \
  -H "Authorization: Bearer pk_YOUR_USER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "claude-code-prod",
    "description": "Production deployment assistant"
  }'

Deactivate an agent

DELETE /agents/:agentId

Soft-deactivates the agent. All of its API keys immediately stop working. The agent record is retained for audit purposes.

curl -X DELETE https://patina.so/api/v1/workspaces/WORKSPACE_ID/agents/AGENT_ID \
  -H "Authorization: Bearer pk_YOUR_USER_KEY"

Create an agent key

POST /agents/:agentId/keys

Creates a new API key for the agent. The full key is returned once — store it securely. An agent can have multiple active keys (e.g. one per environment).

curl -X POST https://patina.so/api/v1/workspaces/WORKSPACE_ID/agents/AGENT_ID/keys \
  -H "Authorization: Bearer pk_YOUR_USER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "production"}'

{
  "id": "key_abc123...",
  "label": "production",
  "key": "pk_9f3a1b2c4d5e6f7890abcdef12345678...",
  "prefix": "pk_9f3a1b2c",
  "createdAt": "2025-03-15T10:05:00.000Z"
}

List agent keys

GET /agents/:agentId/keys

Returns all active keys for the agent. Only the prefix is shown — full keys are never retrievable.

curl https://patina.so/api/v1/workspaces/WORKSPACE_ID/agents/AGENT_ID/keys \
  -H "Authorization: Bearer pk_YOUR_USER_KEY"

Revoke a key

DELETE /agents/:agentId/keys/:keyId

Revokes a key immediately. Any request using this key will return 401.

curl -X DELETE https://patina.so/api/v1/workspaces/WORKSPACE_ID/agents/AGENT_ID/keys/KEY_ID \
  -H "Authorization: Bearer pk_YOUR_USER_KEY"

Full example: register an agent and use it

This script creates an agent, gives it a key, and uses that key to list approved playbooks — the typical setup flow for a new integration.

# 1. Create the agent
AGENT_ID=$(curl -s -X POST https://patina.so/api/v1/workspaces/WORKSPACE_ID/agents \
  -H "Authorization: Bearer pk_YOUR_USER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "deploy-bot", "role": "viewer"}' | jq -r '.id')

# 2. Create an API key for it
API_KEY=$(curl -s -X POST https://patina.so/api/v1/workspaces/WORKSPACE_ID/agents/$AGENT_ID/keys \
  -H "Authorization: Bearer pk_YOUR_USER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "production"}' | jq -r '.key')

# 3. Use the agent key to fetch playbooks
curl https://patina.so/api/v1/workspaces/WORKSPACE_ID/playbooks?status=approved \
  -H "Authorization: Bearer $API_KEY"

Next: Error Handling