Buy

curl --request POST \
  --url https://api.agentcard.sh/buy \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ask": "a 16 oz bag of Colombian ground coffee from Amazon, ship it to 1900 Jefferson St, San Francisco"
}
'

{
  "conversation_id": "<string>",
  "reply": "<string>",
  "messages": [
    "<string>"
  ],
  "message_id": "<string>",
  "cart": {
    "merchant": "<string>",
    "merchant_name": "<string>",
    "items": [
      {
        "name": "<string>",
        "qty": 123,
        "priceCents": 123
      }
    ],
    "serviceFeesCents": 123,
    "tipCents": 123,
    "totalCents": 123,
    "hash": "<string>"
  },
  "carts": [
    {
      "merchant": "<string>",
      "merchant_name": "<string>",
      "items": [
        {
          "name": "<string>",
          "qty": 123,
          "priceCents": 123
        }
      ],
      "serviceFeesCents": 123,
      "tipCents": 123,
      "totalCents": 123,
      "hash": "<string>"
    }
  ],
  "placements": [
    {
      "merchant": "<string>",
      "merchant_name": "<string>",
      "reply": "<string>",
      "error_code": "<string>"
    }
  ],
  "catalog": {
    "merchant": "<string>",
    "merchant_name": "<string>",
    "store": {
      "id": "<string>",
      "name": "<string>"
    },
    "items": [
      {
        "id": "<string>",
        "name": "<string>",
        "priceCents": 123
      }
    ],
    "as_of": "2023-11-07T05:31:56Z"
  },
  "error_code": "<string>"
}

{
  "error": "<string>",
  "hint": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "cart changed since that hash was issued — verify the current carts and confirm their hashes",
  "conversation_id": "cmsq18x2m00a1",
  "cart": {
    "merchant": "retail",
    "merchant_name": "Amazon",
    "items": [
      {
        "name": "Cafe Mesa de los Santos Colombian Ground Coffee, 16 oz",
        "qty": 1,
        "priceCents": 2450
      }
    ],
    "serviceFeesCents": 61,
    "tipCents": 0,
    "totalCents": 2511,
    "hash": "31d8a6e0c47b92f5"
  },
  "carts": [
    {
      "merchant": "retail",
      "merchant_name": "Amazon",
      "items": [
        {
          "name": "Cafe Mesa de los Santos Colombian Ground Coffee, 16 oz",
          "qty": 1,
          "priceCents": 2450
        }
      ],
      "serviceFeesCents": 61,
      "tipCents": 0,
      "totalCents": 2511,
      "hash": "31d8a6e0c47b92f5"
    }
  ]
}

{
  "error": "<string>",
  "conversation_id": "<string>",
  "placements": [
    {}
  ],
  "error_code": "<string>"
}

POST

buy

curl --request POST \
  --url https://api.agentcard.sh/buy \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ask": "a 16 oz bag of Colombian ground coffee from Amazon, ship it to 1900 Jefferson St, San Francisco"
}
'

{
  "conversation_id": "<string>",
  "reply": "<string>",
  "messages": [
    "<string>"
  ],
  "message_id": "<string>",
  "cart": {
    "merchant": "<string>",
    "merchant_name": "<string>",
    "items": [
      {
        "name": "<string>",
        "qty": 123,
        "priceCents": 123
      }
    ],
    "serviceFeesCents": 123,
    "tipCents": 123,
    "totalCents": 123,
    "hash": "<string>"
  },
  "carts": [
    {
      "merchant": "<string>",
      "merchant_name": "<string>",
      "items": [
        {
          "name": "<string>",
          "qty": 123,
          "priceCents": 123
        }
      ],
      "serviceFeesCents": 123,
      "tipCents": 123,
      "totalCents": 123,
      "hash": "<string>"
    }
  ],
  "placements": [
    {
      "merchant": "<string>",
      "merchant_name": "<string>",
      "reply": "<string>",
      "error_code": "<string>"
    }
  ],
  "catalog": {
    "merchant": "<string>",
    "merchant_name": "<string>",
    "store": {
      "id": "<string>",
      "name": "<string>"
    },
    "items": [
      {
        "id": "<string>",
        "name": "<string>",
        "priceCents": 123
      }
    ],
    "as_of": "2023-11-07T05:31:56Z"
  },
  "error_code": "<string>"
}

{
  "error": "<string>",
  "hint": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "cart changed since that hash was issued — verify the current carts and confirm their hashes",
  "conversation_id": "cmsq18x2m00a1",
  "cart": {
    "merchant": "retail",
    "merchant_name": "Amazon",
    "items": [
      {
        "name": "Cafe Mesa de los Santos Colombian Ground Coffee, 16 oz",
        "qty": 1,
        "priceCents": 2450
      }
    ],
    "serviceFeesCents": 61,
    "tipCents": 0,
    "totalCents": 2511,
    "hash": "31d8a6e0c47b92f5"
  },
  "carts": [
    {
      "merchant": "retail",
      "merchant_name": "Amazon",
      "items": [
        {
          "name": "Cafe Mesa de los Santos Colombian Ground Coffee, 16 oz",
          "qty": 1,
          "priceCents": 2450
        }
      ],
      "serviceFeesCents": 61,
      "tipCents": 0,
      "totalCents": 2511,
      "hash": "31d8a6e0c47b92f5"
    }
  ]
}

{
  "error": "<string>",
  "conversation_id": "<string>",
  "placements": [
    {}
  ],
  "error_code": "<string>"
}

Authorizations

Authorization

string

header

required

The user's connection access_token (user authentication), or an org-minted buy_token for org-owned accounts.

Body

application/json

Option 1
Option 2

ask

string

required

What the user wants, in plain language. Required unless the call is a confirm.

Minimum string length: 1

Pattern: \S

conversation_id

string

The thread to continue. A confirm always requires it.

Minimum string length: 1

confirm

A cart hash from a previous response (16 hex characters), or an array of hashes to place several carts. An array confirm cannot carry an ask in the same call.

Pattern: ^[0-9a-f]{16}$

Response

One turn of the purchase conversation, in the fixed envelope.

The fixed response envelope. Every field is present on every response, null when empty.

conversation_id

string

required

Thread it back on every follow-up. Returned on the first call too.

status

enum<string>

required

needs_input is progress, not failure: the reply is a question or a cart waiting on confirmation.

Available options:

needs_input,

order_placed,

partially_placed,

declined

string

required

The assistant's turn as prose, ready to show a human.

messages

string[]

required

The same turn split into ordered bubbles for chat surfaces.

message_id

string

required

cart

object | null

required

The most recently shown cart. Null when no cart is on the table.

Show child attributes

carts

object[]

required

Every open cart in the conversation, oldest first. A conversation can hold carts at several merchants.

Show child attributes

placements

object[] | null

required

Per-cart outcomes of a multi-cart confirm; null on every other call. Partial success is representable here.

Show child attributes

catalog

object | null

required

The last product search as data, with a freshness stamp. Null when nothing fresh was searched.

Show child attributes

error_code

string | null

required

Machine-readable failure code when something went wrong.

⌘I

Authentication

Connect

Add a card

Balance

Withdrawals

Identity verification

Platform connect

Authorizations

Body

Response