Actions

For anything the app does on a screen or the agent does in a turn. One route dispatches every catalog action at the key owner's own access level on the project: a viewer's key reads, an editor's key writes. An action relay performs in the request answers inline; every other one lands as a launched card on your API thread, one reserved run per project and key owner, and you stream its result from that run. A send outside the project or a bulk write never runs on its own: it stages its confirmation on the thread, as it does in the app. The catalog read lists every action with how it runs.

POST/v1/api/actionsAPI key

Dispatch an inline action

Run an action relay performs in the request and read its result in the answer.

An action whose `runs` is `inline` answers 200 with `{action, result}`. A long write answers a `{taskId, status}` to poll rather than holding the request.

Body

Field	Type	Required	Description
action	string	required	The catalog action's id.
input	object	optional	The action's declared input fields; the catalog read carries each action's schema.

Request · curl

curl -X POST "https://runlogai.com/runlogapi/api/actions" \
  -H "Authorization: Bearer $RUNLOG_API_KEY" \
  -H "X-Project-Id: p7Kd2mQx" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "memory_remember",
  "input": {
    "statement": "Invoices settle net-30 unless the contract says otherwise."
  }
}'

Response · 200

{
  "action": "memory_remember",
  "result": {
    "action": "queued",
    "runId": "run_9Fb3TnQ2"
  }
}

Errors

Status	error	When
403	editor access required	The action writes, and the key owner holds view-only access on the project.
404	unknown action	No catalog action has that id; the catalog read lists every one.
400	invalid request body	The body is not JSON, or exceeds the 1 MB request-body cap.
401	invalid API key	The `Authorization` header is missing, malformed, or names a revoked key.
400	name the target project via the X-Project-Id header or projectId query	No project was named and the key is not bound to one.
429	rate limit exceeded	You passed 60 requests/minute on this key. `Retry-After` carries the seconds to wait.
500	internal error	The relay failed to serve the request. Retry with backoff; the cause is logged server-side against your request.

POST/v1/api/actionsAPI key

Dispatch a thread action

Launch an action on your API thread and stream what the turn does with it.

An action whose `runs` is `thread` answers 202 with the run and the message that launched it. The thread is created on first use and reused after, so every thread dispatch of one key owner on one project reads back as one conversation.

A send outside the project or a bulk write lands as a card asking to confirm; the turn performs it once someone answers yes on the thread, in the app or through the run's question routes.

Body

Field	Type	Required	Description
action	string	required	The catalog action's id.
input	object	optional	The action's declared input fields; the catalog read carries each action's schema.

The flow

# 1. Dispatch: the answer names the run and the launching message.
curl -X POST "https://runlogai.com/runlogapi/api/actions" -H "Authorization: Bearer $RUNLOG_API_KEY" \
  -H "X-Project-Id: $PROJECT" -d '{"action":"entity_list","input":{"entityType":"Person"}}'
# → 202 {"action":"entity_list","runId":"run_9Fb3TnQ2","messageId":"m_4Tq8","status":"started"}

# 2. Mint a stream ticket on that run, then open its stream.
curl -X POST "https://runlogai.com/runlogapi/api/agent-runs/run_9Fb3TnQ2/stream-ticket" -H "Authorization: Bearer $RUNLOG_API_KEY"
curl -N "https://runlogai.com/runlogapi/api/agent-runs/run_9Fb3TnQ2/stream?ticket=$TICKET"

Request · curl

curl -X POST "https://runlogai.com/runlogapi/api/actions" \
  -H "Authorization: Bearer $RUNLOG_API_KEY" \
  -H "X-Project-Id: p7Kd2mQx" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "entity_list",
  "input": {
    "entityType": "Person"
  }
}'

Response · 202

{
  "action": "entity_list",
  "messageId": "m_4Tq8",
  "runId": "run_9Fb3TnQ2",
  "status": "started"
}

Errors

Status	error	When
403	editor access required	The action writes, and the key owner holds view-only access on the project.
404	unknown action	No catalog action has that id; the catalog read lists every one.
400	invalid request body	The body is not JSON, or exceeds the 1 MB request-body cap.
401	invalid API key	The `Authorization` header is missing, malformed, or names a revoked key.
400	name the target project via the X-Project-Id header or projectId query	No project was named and the key is not bound to one.
429	rate limit exceeded	You passed 60 requests/minute on this key. `Retry-After` carries the seconds to wait.
500	internal error	The relay failed to serve the request. Retry with backoff; the cause is logged server-side against your request.