Agents

DEPRECATED

This API is deprecated and remains available for existing integrations. New integrations should use payment methods and allowances. No removal date has been announced.

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 (1–255 characters)
enrollment_ids	No	string[]	List of enrollment IDs to associate with this agent (max 50)
instance_details	No	object	Device information for the agent. See instance details object

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 (1–255 characters)
enrollment_ids	No	string[]	Updated list of enrollment IDs to associate with this agent (max 50)
instance_details	No	object	Updated device information. See instance details object

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
instance_details	object	Device information for the agent (if provided)
created_at	string	ISO 8601 timestamp of when the agent was created

Instance Details Object

Attribute	Required	Type	Description
ip_address	No	string	IPv4 address of the device
brand	No	string	Device brand name
type	No	string	Device type. One of: mobile-phone, tablet, laptop, personal-assistant, connected-auto, home-appliance, wearable, stationary-computer, e-reader, handheld-gaming-device, other