---
title: "Tap a card's button"
method: POST
path: "/api/v1/cards/{id}/actions"
tags: ["Cards"]
---

# Tap a card's button

`POST /api/v1/cards/{id}/actions`

## Request

- Base URL: `https://saltapp.ai`
- URL: `https://saltapp.ai/api/v1/cards/{id}/actions`
- Auth: API key in header `api-key`

Dispatch is on the button's own server-recorded action_type, NEVER its label: `pay` creates a real TransferRequest against the owner's matching-currency wallet (refused for a guest session -- see 403); `handoff` runs the same authorized hand-off chats#hand_off uses; `signup` (guest chats) is never forwarded anywhere; anything else forwards to the card owner's webhook/socket outbox as a card_interaction event. `values` is an optional {block_id => answer} map answering the card's own `input` blocks -- every key must name an input block this card declares and every value must be a string no longer than that block's own max_length, else a 422 with one plain sentence. A pay, handoff or signup button ignores `values` entirely.

## Path parameters

- `id` string, required

## Request body

- object
  - `action_id` string, required
  - `value` string
  - `values` object: {block_id => answer}, for the card's own input blocks. Ignored by a pay or handoff button.

## Response `200`

OK.

- object
  - `ok` boolean
  - `dispatched` 'pay' | 'handoff' | 'signup' | 'link' | 'interaction'
  - `transfer_request_id` string
  - `active_agent_id` string

## Other responses

- `401`: Missing or invalid credentials.
- `403`: You're not allowed to do that. (restricted_to) / Create a free account to do that. (guest tapping a pay button)
- `404`: No such action on this card.
- `422`: no_wallet_for_currency / You can't pay your own card. / hand-off refusal. / That card has no such field. / That answer is too long.

---

[API](https://skmtc.dev/saltapp/apis/salt-agent-api.md) · [All operations](https://skmtc.dev/saltapp/apis/salt-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/saltapp/apis/salt-agent-api/revisions/a8b8642ab7f8?raw)