Send a message or click an agent card action

POST

/api/v1/agents/{id}/messages

Code sample: cURL — click Save

curl -X POST 'https://api.justcrawl.io/api/v1/agents/AGENT_ID/messages' \
  -H 'Authorization: Bearer $JUSTCRAWL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"action":{"cardId":"SAVE_OFFER_CARD_ID","actionId":"accept"}}'

• Production

Queues one agent turn. For a card click, send only the stored cardId, actionId, and optional stored value. The gateway reloads the tenant-owned card, validates the action, authors canonical transcript text, and refuses altered or already-used one-shot actions. A save_query_offer is accepted only through this click route; typed text and model/tool calls cannot authorize saving. Accepting that offer also requires bi:write; declining it and other card actions require workflows:write.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

Agent and conversation id.

Request Body^required

Media typeapplication/json

Any of:

object

object

content

required

string

>= 1 characters <= 10000 characters

action

A click on an action loaded from the same conversation card. The gateway reloads the stored action and ignores client-authored display text.

object

cardId

required

string format: uuid

actionId

required

string

value

nullable

object

object

content

string

>= 1 characters <= 10000 characters

action

required

A click on an action loaded from the same conversation card. The gateway reloads the stored action and ignores client-authored display text.

object

cardId

required

string format: uuid

actionId

required

string

value

nullable

Example^generated

{
  "content": "example",
  "action": {
    "cardId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "actionId": "example",
    "value": "example"
  }
}

Responses

202

Turn accepted. content is present for card actions and is authored by the server.

Media typeapplication/json

object

turnId

required

string format: uuid

content

string

Example^generated

{
  "turnId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "content": "example"
}

400

Validation failed — request body or query is missing/invalid

Media typeapplication/json

object

error

string

Example

{
  "error": "Missing or invalid \"url\" field"
}

401

Missing or invalid authentication token

Media typeapplication/json

object

error

string

Example

{
  "error": "Missing or invalid authentication token"
}

403

Insufficient permissions for this operation

Media typeapplication/json

object

error

string

Example

{
  "error": "No organization. Complete onboarding first."
}

404

Resource not found

Media typeapplication/json

object

error

string

Example

{
  "error": "Workflow not found"
}

409

The one-shot action was already used or an identical click is still in flight.

Media typeapplication/json

object

error

string

Example^generated

{
  "error": "example"
}

500

Unexpected server error. Logs and PostHog $exception capture

Media typeapplication/json

object

error

string

Example

{
  "error": "Something went wrong"
}