Instructions

Instructions define spending rules for a purchase. Each instruction is tied to an enrollment and specifies an amount, optional description, and optional expiration. The consumer must verify the instruction before virtual card credentials can be retrieved.

Authentication

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

All errors follow the standard error response format.

List Instructions

Returns a paginated list of instructions for an agent.

GET

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

Permissions

agent:instruction:get

Request

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

Request Parameters

Attribute	Required	Type	Description
`agent_id`	Yes	string	The ID of the agent
`enrollment_id`	No	string	Filter instructions by enrollment ID
`limit`	No	integer	Number of results to return (default: 25, max: 100)
`cursor`	No	string	Opaque pagination cursor from a previous response

Response

Returns a paginated list of instruction objects.

{
  "data": [
    {
      "id": "ins_luPDv2xm3Yb8RjFJz9oTC",
      "enrollment_id": "enr_wNe75VKdzvojI9iD5fJxr",
      "status": "approved",
      "amount": {
        "value": "500.00",
        "currency": "USD"
      },
      "expires_at": "2026-02-20T00:00:00Z",
      "created_at": "2026-01-15T10:35:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6Imluc19sdVBEdjJ4bTNZYjhSakZKejlvVEMifQ",
    "has_more": false
  }
}

Create Instruction

Creates a new purchase instruction for an enrollment.

POST

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

Permissions

agent:instruction:create

Request

curl -X POST https://api.basistheory.com/agentic/agents/agt_fukICjsY2xzRCECiTCbKM/instructions \
  -H 'BT-API-KEY: <BT_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "enrollment_id": "enr_wNe75VKdzvojI9iD5fJxr",
    "amount": {
      "value": "500.00",
      "currency": "USD"
    },
    "description": "Purchase electronics",
    "expires_at": "2026-02-20T00:00:00Z"
  }'

Request Parameters

Attribute	Required	Type	Description
`agent_id`	Yes	string	The ID of the agent
`enrollment_id`	Yes	string	The ID of the enrollment to create the instruction for
`amount`	Yes	object	The amount object defining the spending limit
`description`	No	string	A description of the purchase
`expires_at`	No	string	ISO 8601 timestamp for when the instruction expires

Amount Object

Attribute	Required	Type	Description
`value`	Yes	string	The monetary amount (e.g., `"500.00"`)
`currency`	No	string	ISO 4217 currency code (default: `USD`)

Response

Returns an instruction object if successful. The instruction will have pending_verification status until the consumer completes verification.

{
  "id": "ins_luPDv2xm3Yb8RjFJz9oTC",
  "enrollment_id": "enr_wNe75VKdzvojI9iD5fJxr",
  "status": "pending_verification",
  "amount": {
    "value": "500.00",
    "currency": "USD"
  },
  "expires_at": "2026-02-20T00:00:00Z",
  "created_at": "2026-01-15T10:35:00Z"
}

Get Instruction

Retrieves an instruction by ID.

GET

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

Permissions

agent:instruction:get

Request

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

Request Parameters

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

Response

Returns an instruction object if successful.

{
  "id": "ins_luPDv2xm3Yb8RjFJz9oTC",
  "enrollment_id": "enr_wNe75VKdzvojI9iD5fJxr",
  "status": "approved",
  "amount": {
    "value": "500.00",
    "currency": "USD"
  },
  "expires_at": "2026-02-20T00:00:00Z",
  "created_at": "2026-01-15T10:35:00Z"
}

Update Instruction

Updates an existing instruction.

PATCH

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

Permissions

agent:instruction:update

Request

curl -X PATCH https://api.basistheory.com/agentic/agents/agt_fukICjsY2xzRCECiTCbKM/instructions/ins_luPDv2xm3Yb8RjFJz9oTC \
  -H 'BT-API-KEY: <BT_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": {
      "value": "750.00",
      "currency": "USD"
    },
    "expires_at": "2026-03-20T00:00:00Z"
  }'

Request Parameters

Attribute	Required	Type	Description
`agent_id`	Yes	string	The ID of the agent
`instruction_id`	Yes	string	The ID of the instruction to update
`amount`	No	object	Updated amount object
`expires_at`	No	string	Updated ISO 8601 expiration timestamp

Response

Returns the updated instruction object if successful.

{
  "id": "ins_luPDv2xm3Yb8RjFJz9oTC",
  "enrollment_id": "enr_wNe75VKdzvojI9iD5fJxr",
  "status": "approved",
  "amount": {
    "value": "750.00",
    "currency": "USD"
  },
  "expires_at": "2026-03-20T00:00:00Z",
  "created_at": "2026-01-15T10:35:00Z"
}

Delete Instruction

Deletes an instruction.

DELETE

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

Permissions

agent:instruction:delete

Request

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

Request Parameters

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

Response

Returns a 204 No Content response if successful.

Verify Instruction

Instruction verification is a multi-step flow that requires the consumer to authenticate via passkey. The @basis-theory/react-agentic SDK handles this flow automatically via the verifyInstruction() method. The individual endpoints are documented below for reference.

For frontend integration, use the verifyInstruction() method from the @basis-theory/react-agentic SDK's useBtAi hook. It handles the passkey authentication UI. See the Agentic Credentials guide for usage examples.

Verification Flow

Start verification — POST /agents/:id/instructions/:id/verify — initiates passkey challenge.
Submit passkey — POST /agents/:id/instructions/:id/verify/passkey — submits the passkey assertion.

Start Verification

Initiates the instruction verification flow.

POST

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

Permissions

agent:instruction:verify

curl -X POST https://api.basistheory.com/agentic/agents/agt_fukICjsY2xzRCECiTCbKM/instructions/ins_luPDv2xm3Yb8RjFJz9oTC/verify \
  -H 'BT-API-KEY: <BT_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "device_context": {
      "ip_address": "192.168.1.1"
    }
  }'

Returns either { "status": "verified" } if passkeys are bypassed, or a challenge response for passkey authentication.

Submit Passkey

Submits the passkey/FIDO assertion to complete instruction verification.

POST

https://api.basistheory.com/agentic/agents/{agent_id}/instructions/{instruction_id}/verify/passkey

Permissions

agent:instruction:verify

curl -X POST https://api.basistheory.com/agentic/agents/agt_fukICjsY2xzRCECiTCbKM/instructions/ins_luPDv2xm3Yb8RjFJz9oTC/verify/passkey \
  -H 'BT-API-KEY: <BT_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "assurance_data": "<PASSKEY_ASSERTION>"
  }'

After successful verification, the instruction status changes from pending_verification to approved. May return a PASSKEY_FAILED error if the assertion is invalid.

Instruction Object

Attribute	Type	Description
`id`	string	Unique identifier of the instruction
`enrollment_id`	string	The ID of the enrollment this instruction belongs to
`status`	string	The instruction status: `pending`, `pending_verification`, `approved`, `expired`, `cancelled`, or `failed`
`amount`	object	The spending limit. See amount object
`description`	string	A description of the purchase (if provided during creation)
`expires_at`	string	ISO 8601 timestamp for when the instruction expires
`created_at`	string	ISO 8601 timestamp of when the instruction was created

Instruction Statuses

Status	Description
`pending`	Awaiting provider approval
`pending_verification`	Provider approved; awaiting consumer verification via passkey
`approved`	Consumer verified; virtual card credentials can be retrieved
`expired`	Past the `expires_at` time; credentials can no longer be retrieved
`cancelled`	Cancelled before use
`failed`	Verification or provider failure

Credentials can only be retrieved for instructions with approved status.

Pagination

List endpoints use cursor-based pagination.

Attribute	Type	Description
`pagination.next_cursor`	string	Opaque cursor for the next page (absent when no more results)
`pagination.has_more`	boolean	Whether there are more results beyond this page

Pass next_cursor as the cursor query parameter to retrieve the next page.

Authentication​

List Instructions​

Permissions​

Request​

Request Parameters​

Response​

Create Instruction​

Permissions​

Request​

Request Parameters​

Amount Object​

Response​

Get Instruction​

Permissions​

Request​

Request Parameters​

Response​

Update Instruction​

Permissions​

Request​

Request Parameters​

Response​

Delete Instruction​

Permissions​

Request​

Request Parameters​

Response​

Verify Instruction​

Verification Flow​

Start Verification​

Permissions​

Submit Passkey​

Permissions​

Instruction Object​

Instruction Statuses​

Pagination​

Authentication

List Instructions

Permissions

Request

Request Parameters

Response

Create Instruction

Permissions

Request

Request Parameters

Amount Object

Response

Get Instruction

Permissions

Request

Request Parameters

Response

Update Instruction

Permissions

Request

Request Parameters

Response

Delete Instruction

Permissions

Request

Request Parameters

Response

Verify Instruction

Verification Flow

Start Verification

Permissions

Submit Passkey

Permissions

Instruction Object

Instruction Statuses

Pagination