Agents

Agents represent AI assistants that make purchases on behalf of consumers. Each agent has a name and can manage multiple enrollments and instructions.

Authentication

All requests require a BT-API-KEY header with your Basis Theory API key.

All errors follow the standard error response format.

Create Agent

Creates a new agent.

POST

https://api.basistheory.com/agentic/agents

Permissions

agent:create

Request

curl -X POST https://api.basistheory.com/agentic/agents \
  -H 'BT-API-KEY: <BT_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Shopping Assistant",
    "enrollment_ids": ["enr_wNe75VKdzvojI9iD5fJxr"]
  }'

Request Parameters

Attribute	Required	Type	Description
name	Yes	string	The name of the agent
enrollment_ids	No	string[]	List of enrollment IDs to associate with this agent (max 50)

Response

Returns an agent object if successful.

{
  "id": "agt_fukICjsY2xzRCECiTCbKM",
  "name": "Shopping Assistant",
  "enrollment_ids": ["enr_wNe75VKdzvojI9iD5fJxr"],
  "status": "active",
  "created_at": "2026-01-15T10:30:00Z"
}

Get Agent

Retrieves an agent by ID.

GET

https://api.basistheory.com/agentic/agents/{agent_id}

Permissions

agent:get

Request

curl https://api.basistheory.com/agentic/agents/agt_fukICjsY2xzRCECiTCbKM \
  -H 'BT-API-KEY: <BT_API_KEY>'

Request Parameters

Attribute	Required	Type	Description
agent_id	Yes	string	The ID of the agent to retrieve

Response

Returns an agent object if successful.

{
  "id": "agt_fukICjsY2xzRCECiTCbKM",
  "name": "Shopping Assistant",
  "enrollment_ids": ["enr_wNe75VKdzvojI9iD5fJxr"],
  "status": "active",
  "created_at": "2026-01-15T10:30:00Z"
}

Update Agent

Updates an existing agent.

PATCH

https://api.basistheory.com/agentic/agents/{agent_id}

Permissions

agent:update

Request

curl -X PATCH https://api.basistheory.com/agentic/agents/agt_fukICjsY2xzRCECiTCbKM \
  -H 'BT-API-KEY: <BT_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Updated Assistant Name",
    "enrollment_ids": ["enr_wNe75VKdzvojI9iD5fJxr", "enr_abc123"]
  }'

Request Parameters

Attribute	Required	Type	Description
agent_id	Yes	string	The ID of the agent to update
name	No	string	The updated name of the agent
enrollment_ids	No	string[]	Updated list of enrollment IDs to associate with this agent (max 50)

Response

Returns the updated agent object if successful.

{
  "id": "agt_fukICjsY2xzRCECiTCbKM",
  "name": "Updated Assistant Name",
  "enrollment_ids": ["enr_wNe75VKdzvojI9iD5fJxr", "enr_abc123"],
  "status": "active",
  "created_at": "2026-01-15T10:30:00Z"
}

Delete Agent

Deletes an agent.

DELETE

https://api.basistheory.com/agentic/agents/{agent_id}

Permissions

agent:delete

Request

curl -X DELETE https://api.basistheory.com/agentic/agents/agt_fukICjsY2xzRCECiTCbKM \
  -H 'BT-API-KEY: <BT_API_KEY>'

Request Parameters

Attribute	Required	Type	Description
agent_id	Yes	string	The ID of the agent to delete

Response

Returns a 204 No Content response if successful.

Agent Object

Attribute	Type	Description
id	string	Unique identifier of the agent
name	string	The name of the agent
enrollment_ids	string[]	List of enrollment IDs associated with this agent
status	string	The status of the agent. Possible values: active
created_at	string	ISO 8601 timestamp of when the agent was created