API Reference

Auto-generated

Hands

API reference for hands endpoints.

Auto-generated

This page was generated from the OpenAPI spec. Runmake generate-docs to refresh after spec changes.

GET /api/v1/hands/access/invites

GET

/api/v1/hands/access/invites

Your invite links

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/access/invites \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "quota": 0,
  "invites": []
}

POST /api/v1/hands/access/join

POST

/api/v1/hands/access/join

Join the Hands queue

Parameters

Name	Type	Required	Description
invite_code	`string`	Optional	invite_code

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/access/join \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "state": "example",
  "admitted": true,
  "admissions_open": true,
  "position": "example",
  "waiting": 0,
  "points": "example"
}

GET /api/v1/hands/access/me

GET

/api/v1/hands/access/me

Queue state and position

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/access/me \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "state": "example",
  "admitted": true,
  "admissions_open": true,
  "position": "example",
  "waiting": 0,
  "points": "example"
}

POST /api/v1/hands/access/redeem

POST

/api/v1/hands/access/redeem

Redeem an invite code

Parameters

Name	Type	Required	Description
code	`string`	Required	Code

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/access/redeem \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "example_code"
  }'

Response Example

JSON

{
  "state": "example",
  "admitted": true,
  "admissions_open": true,
  "position": "example",
  "waiting": 0,
  "points": "example"
}

POST /api/v1/hands/access/request

POST

/api/v1/hands/access/request

An agent requests Hands access for its user

Parameters

Name	Type	Required	Description
resume_ref	`string`	Optional	resume_ref
invite_code	`string`	Optional	invite_code

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/access/request \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "state": "example",
  "admitted": true,
  "admissions_open": true,
  "position": "example",
  "waiting": 0,
  "points": "example"
}

GET /api/v1/hands/access/rules

GET

/api/v1/hands/access/rules

The published queue rules

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/access/rules \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/accounts

GET

/api/v1/hands/accounts

Get Account Map

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/accounts \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/accounts/resolve

POST

/api/v1/hands/accounts/resolve

Resolve Accounts

Parameters

Name	Type	Required	Description
targets	`object[]`	Required	Targets

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/accounts/resolve \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": []
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/alerts

GET

/api/v1/hands/alerts

Hands List Alerts

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/alerts \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "alerts": []
}

POST /api/v1/hands/alerts/notify-pending

POST

/api/v1/hands/alerts/notify-pending

Hands Notify Pending Alerts

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/alerts/notify-pending \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/artifacts

POST

/api/v1/hands/artifacts

Upload Artifact

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/artifacts \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/artifacts

GET

/api/v1/hands/artifacts

List Artifacts

Parameters

Name	Type	Required	Description
limit	`integer`	Optional	limitDefault: `50`

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/artifacts \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "artifacts": []
}

POST /api/v1/hands/artifacts/from-task-file

POST

/api/v1/hands/artifacts/from-task-file

Parameters

Name	Type	Required	Description
task_id	`string`	Required	Task Id
file_id	`string`	Required	File Id
retention_s	`integer`	Optional	retention_s

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/artifacts/from-task-file \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "example_task_id",
    "file_id": "example_file_id"
  }'

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/artifacts/from-url

POST

/api/v1/hands/artifacts/from-url

Parameters

Name	Type	Required	Description
url	`string`	Required	Public http(s) URL to fetch and register
filename	`string`	Optional	filename
retention_s	`integer`	Optional	retention_s

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/artifacts/from-url \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "example_url"
  }'

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/artifacts/verify-link

POST

/api/v1/hands/artifacts/verify-link

Verify Link

Parameters

Name	Type	Required	Description
url	`string`	Required	Url
sha256	`string`	Optional	sha256
artifact_id	`string`	Optional	artifact_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/artifacts/verify-link \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "example_url"
  }'

Response Example

JSON

{
  "status": 0,
  "content_type": "example",
  "hash_matches": "example",
  "requires_login": true,
  "ok": true
}

GET /api/v1/hands/artifacts/{artifact_id}

GET

/api/v1/hands/artifacts/{artifact_id}

Read Artifact

Parameters

Name	Type	Required	Description
artifact_id	`string`	Required	artifact_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/artifacts/<artifact_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "artifact_id": "example",
  "filename": "example",
  "mime": "example",
  "size": 0,
  "sha256": "example",
  "origin": "example"
}

DELETE /api/v1/hands/artifacts/{artifact_id}

DELETE

/api/v1/hands/artifacts/{artifact_id}

Remove Artifact

Parameters

Name	Type	Required	Description
artifact_id	`string`	Required	artifact_id

Request Example

Bash

curl -X DELETE https://api.alterlab.io/api/v1/hands/artifacts/<artifact_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/audit

GET

/api/v1/hands/audit

Hands List Audit

Parameters

Name	Type	Required	Description
limit	`integer`	Optional	limitDefault: `50`
before_id	`integer`	Optional	before_id
task_id	`string`	Optional	task_id
outcome	`string`	Optional	outcome

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/audit \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "entries": [],
  "next_before_id": "example"
}

GET /api/v1/hands/audit/export

GET

/api/v1/hands/audit/export

Hands Export Audit

Parameters

Name	Type	Required	Description
format	`string`	Optional	formatDefault: `csv`
include	`string`	Optional	receipts: add the signed outcome receipts (JSON only; the default shape is unchanged)

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/audit/export \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/budgets

GET

/api/v1/hands/budgets

Hands Get Budgets

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/budgets \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "site_classes": [],
  "pacing": {}
}

PUT /api/v1/hands/budgets

PUT

/api/v1/hands/budgets

Put Budgets

Parameters

Name	Type	Required	Description
site_class	`string`	Required	Site Class
limits	`object`	Optional	Limits
median_s	`number`	Optional	median_s
working_hours_start	`integer`	Optional	working_hours_start
working_hours_end	`integer`	Optional	working_hours_end
utc_offset_minutes	`integer`	Optional	Utc Offset MinutesDefault: `0`

Request Example

Bash

curl -X PUT https://api.alterlab.io/api/v1/hands/budgets \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "site_class": "example_site_class"
  }'

Response Example

JSON

{
  "site_classes": [],
  "pacing": {}
}

POST /api/v1/hands/connect

POST

/api/v1/hands/connect

Ask the user to connect a site

Parameters

Name	Type	Required	Description
site	`string`	Required	Site
scopes	`string[]`	Optional	scopes
reason	`string`	Optional	Reason
task_ref	`string`	Optional	task_ref

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/connect \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "site": "example_site",
    "reason": "example_reason"
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/connect/{connect_id}

GET

/api/v1/hands/connect/{connect_id}

Poll a connect request

Parameters

Name	Type	Required	Description
connect_id	`string`	Required	connect_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/connect/<connect_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/connect/{connect_id}/complete

POST

/api/v1/hands/connect/{connect_id}/complete

Bind the approved session handle

Parameters

Name	Type	Required	Description
connect_id	`string`	Required	connect_id
session_id	`string`	Required	Session Id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/connect/<connect_id>/complete \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "example_session_id"
  }'

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/connect/{connect_id}/view

POST

/api/v1/hands/connect/{connect_id}/view

Record that the user opened a connect request

Parameters

Name	Type	Required	Description
connect_id	`string`	Required	connect_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/connect/<connect_id>/view \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/content/check

POST

/api/v1/hands/content/check

Content Check

Parameters

Name	Type	Required	Description
content	`object`	Required	Outward text Hands will write for the user, with its claim bindings.
must_be_user_authored	`boolean`	Optional	Policy mark: the text is a personal statement only the user may authorDefault: `False`

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/content/check \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "...",
    "must_be_user_authored": false
  }'

Response Example

JSON

{
  "status": "example",
  "issues": [],
  "claims": [],
  "bindings": [],
  "content_hash": "example"
}

GET /api/v1/hands/context-sources

GET

/api/v1/hands/context-sources

List Context Sources

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/context-sources \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "sources": []
}

PUT /api/v1/hands/context-sources/{source}

PUT

/api/v1/hands/context-sources/{source}

Toggle Context Source

Parameters

Name	Type	Required	Description
source	`string`	Required	source
enabled	`boolean`	Required	Enabled

Request Example

Bash

curl -X PUT https://api.alterlab.io/api/v1/hands/context-sources/<source> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

Response Example

JSON

{
  "sources": []
}

DELETE /api/v1/hands/context-sources/{source}

DELETE

/api/v1/hands/context-sources/{source}

Revoke Context Source

Parameters

Name	Type	Required	Description
source	`string`	Required	source

Request Example

Bash

curl -X DELETE https://api.alterlab.io/api/v1/hands/context-sources/<source> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "source": "example",
  "facts_marked_stale": 0
}

POST /api/v1/hands/conversations

POST

/api/v1/hands/conversations

Create Conversation

Parameters

Name	Type	Required	Description
counterparty	`object`	Required	Counterparty
channel	`string`	Required	Channel
goal	`object`	Required	Goal
limits	`object`	Optional	Set by the user at creation; nothing an inbound message says can change them.
persona	`object`	Optional	Persona
sender	`string`	Optional	sender
thread_ref	`string`	Optional	thread_ref
message_budget	`integer`	Optional	Message BudgetDefault: `10`
min_gap_s	`integer`	Optional	Min Gap SDefault: `60`
follow_up_delay_s	`integer`	Optional	follow_up_delay_s
follow_up_text	`string`	Optional	follow_up_text

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/conversations \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "counterparty": "...",
    "channel": "example_channel",
    "goal": "..."
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/conversations

GET

/api/v1/hands/conversations

List Conversations

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/conversations \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "items": []
}

GET /api/v1/hands/conversations/{conversation_id}

GET

/api/v1/hands/conversations/{conversation_id}

Get Conversation

Parameters

Name	Type	Required	Description
conversation_id	`string`	Required	conversation_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/conversations/<conversation_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "counterparty": {},
  "channel": "example",
  "goal": {},
  "limits": {},
  "persona": {}
}

POST /api/v1/hands/conversations/{conversation_id}/inbound

POST

/api/v1/hands/conversations/{conversation_id}/inbound

Post Inbound

Parameters

Name	Type	Required	Description
conversation_id	`string`	Required	conversation_id
body	`string`	Required	Body
external_id	`string`	Optional	external_id
source	`string`	Optional	SourceDefault: `mailbox`

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/conversations/<conversation_id>/inbound \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "example_body",
    "source": "example_source"
  }'

Response Example

JSON

{
  "message": "example",
  "conversation": "example"
}

GET /api/v1/hands/conversations/{conversation_id}/messages

GET

/api/v1/hands/conversations/{conversation_id}/messages

List Messages

Parameters

Name	Type	Required	Description
conversation_id	`string`	Required	conversation_id
limit	`integer`	Optional	limitDefault: `200`

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/conversations/<conversation_id>/messages \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "items": []
}

POST /api/v1/hands/conversations/{conversation_id}/messages

POST

/api/v1/hands/conversations/{conversation_id}/messages

Draft Message Endpoint

Parameters

Name	Type	Required	Description
conversation_id	`string`	Required	conversation_id
body	`string`	Required	Body
claims	`object[]`	Optional	Claims

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/conversations/<conversation_id>/messages \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "example_body"
  }'

Response Example

JSON

{
  "message": "example",
  "decision": "example",
  "reasons": [],
  "dispatch": "example"
}

POST /api/v1/hands/conversations/{conversation_id}/messages/{message_id}/approve

POST

/api/v1/hands/conversations/{conversation_id}/messages/{message_id}/approve

Approve Message Endpoint

Parameters

Name	Type	Required	Description
conversation_id	`string`	Required	conversation_id
message_id	`string`	Required	message_id
content_hash	`string`	Required	content_hash

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/conversations/<conversation_id>/messages/<message_id>/approve \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/conversations/{conversation_id}/messages/{message_id}/dispatch

POST

/api/v1/hands/conversations/{conversation_id}/messages/{message_id}/dispatch

Dispatch Message

Parameters

Name	Type	Required	Description
conversation_id	`string`	Required	conversation_id
message_id	`string`	Required	message_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/conversations/<conversation_id>/messages/<message_id>/dispatch \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/conversations/{conversation_id}/messages/{message_id}/report

POST

/api/v1/hands/conversations/{conversation_id}/messages/{message_id}/report

Report Message

Parameters

Name	Type	Required	Description
conversation_id	`string`	Required	conversation_id
message_id	`string`	Required	message_id
outcome	`string`	Required	Outcome
external_id	`string`	Optional	external_id
thread_ref	`string`	Optional	thread_ref

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/conversations/<conversation_id>/messages/<message_id>/report \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "outcome": "example_outcome"
  }'

Response Example

JSON

{
  "id": "example",
  "counterparty": {},
  "channel": "example",
  "goal": {},
  "limits": {},
  "persona": {}
}

POST /api/v1/hands/conversations/{conversation_id}/stop

POST

/api/v1/hands/conversations/{conversation_id}/stop

Stop Conversation

Parameters

Name	Type	Required	Description
conversation_id	`string`	Required	conversation_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/conversations/<conversation_id>/stop \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "counterparty": {},
  "channel": "example",
  "goal": {},
  "limits": {},
  "persona": {}
}

POST /api/v1/hands/credential-requests

POST

/api/v1/hands/credential-requests

Ask the user for a credential

Parameters

Name	Type	Required	Description
task_id	`string`	Required	Task Id
domain	`string`	Required	Domain
fields	`object[]`	Required	Fields
reuse	`"once" \| "task" \| "standing"`	Optional	ReuseDefault: `once`
reason	`string`	Optional	Reason
expires_in_s	`integer`	Optional	Expires In SDefault: `900`
use_limit	`integer`	Optional	use_limit
valid_for_days	`integer`	Optional	valid_for_days
ask_each_time	`boolean`	Optional	Ask Each TimeDefault: `False`

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/credential-requests \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "example_task_id",
    "domain": "example_domain",
    "fields": [],
    "reuse": "...",
    "reason": "example_reason"
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/credential-requests

GET

/api/v1/hands/credential-requests

List credential requests

Parameters

Name	Type	Required	Description
task_id	`string`	Optional	task_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/credential-requests \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "requests": []
}

GET /api/v1/hands/credential-requests/standing

GET

/api/v1/hands/credential-requests/standing

Standing credentials a task on the same domain can reuse

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id

Request Example

Bash

curl -X GET 'https://api.alterlab.io/api/v1/hands/credential-requests/standing?task_id=<task_id>' \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "requests": []
}

GET /api/v1/hands/credential-requests/{request_id}

GET

/api/v1/hands/credential-requests/{request_id}

Poll a credential request

Parameters

Name	Type	Required	Description
request_id	`string`	Required	request_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/credential-requests/<request_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "request_id": "example",
  "task_id": "example",
  "domain": "example",
  "fields": [],
  "reuse": "example",
  "reason": "example"
}

DELETE /api/v1/hands/credential-requests/{request_id}

DELETE

/api/v1/hands/credential-requests/{request_id}

Delete a credential request and its stored ciphertext

Parameters

Name	Type	Required	Description
request_id	`string`	Required	request_id

Request Example

Bash

curl -X DELETE https://api.alterlab.io/api/v1/hands/credential-requests/<request_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/credential-requests/{request_id}/confirm

POST

/api/v1/hands/credential-requests/{request_id}/confirm

Let one later task use an ask-each-time standing credential

Parameters

Name	Type	Required	Description
request_id	`string`	Required	request_id
task_id	`string`	Required	Task Id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/credential-requests/<request_id>/confirm \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "example_task_id"
  }'

Response Example

JSON

{
  "request_id": "example",
  "task_id": "example",
  "domain": "example",
  "fields": [],
  "reuse": "example",
  "reason": "example"
}

POST /api/v1/hands/credential-requests/{request_id}/confirm/email-code

POST

/api/v1/hands/credential-requests/{request_id}/confirm/email-code

Email a 6-digit code that confirms this request

Parameters

Name	Type	Required	Description
request_id	`string`	Required	request_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/credential-requests/<request_id>/confirm/email-code \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "sent": true,
  "expires_in": 0
}

POST /api/v1/hands/credential-requests/{request_id}/confirm/options

POST

/api/v1/hands/credential-requests/{request_id}/confirm/options

Passkey challenge bound to this request and its terms

Parameters

Name	Type	Required	Description
request_id	`string`	Required	request_id
reuse	`"once" \| "task" \| "standing"`	Required	Reuse
ask_each_time	`boolean`	Optional	Ask Each TimeDefault: `False`
expires_in_days	`integer`	Optional	expires_in_days

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/credential-requests/<request_id>/confirm/options \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reuse": "...",
    "ask_each_time": false
  }'

Response Example

JSON

{
  "nonce": "example",
  "challenge": "example",
  "rpId": "example",
  "allowCredentials": [],
  "userVerification": "example",
  "timeout": 0
}

POST /api/v1/hands/credential-requests/{request_id}/decline

POST

/api/v1/hands/credential-requests/{request_id}/decline

Decline a credential request

Parameters

Name	Type	Required	Description
request_id	`string`	Required	request_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/credential-requests/<request_id>/decline \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "request_id": "example",
  "task_id": "example",
  "domain": "example",
  "fields": [],
  "reuse": "example",
  "reason": "example"
}

GET /api/v1/hands/credential-requests/{request_id}/entry

GET

/api/v1/hands/credential-requests/{request_id}/entry

Entry-page data: envelope public key for browser-side sealing

Parameters

Name	Type	Required	Description
request_id	`string`	Required	request_id
short_code	`string`	Optional	short_code

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/credential-requests/<request_id>/entry \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "request": "example",
  "envelope": {},
  "aad": "example",
  "alternatives": "example"
}

POST /api/v1/hands/credential-requests/{request_id}/handoffs

POST

/api/v1/hands/credential-requests/{request_id}/handoffs

Create a single-use phone handoff (QR) for a credential request

Parameters

Name	Type	Required	Description
request_id	`string`	Required	request_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/credential-requests/<request_id>/handoffs \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/credential-requests/{request_id}/handoffs/{handoff_id}

GET

/api/v1/hands/credential-requests/{request_id}/handoffs/{handoff_id}

Poll a handoff's state

Parameters

Name	Type	Required	Description
request_id	`string`	Required	request_id
handoff_id	`string`	Required	handoff_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/credential-requests/<request_id>/handoffs/<handoff_id> \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "state": "example",
  "device_label": "example"
}

DELETE /api/v1/hands/credential-requests/{request_id}/handoffs/{handoff_id}

DELETE

/api/v1/hands/credential-requests/{request_id}/handoffs/{handoff_id}

Cancel a handoff (take it back on the laptop)

Parameters

Name	Type	Required	Description
request_id	`string`	Required	request_id
handoff_id	`string`	Required	handoff_id

Request Example

Bash

curl -X DELETE https://api.alterlab.io/api/v1/hands/credential-requests/<request_id>/handoffs/<handoff_id> \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/credential-requests/{request_id}/handoffs/{handoff_id}/events

GET

/api/v1/hands/credential-requests/{request_id}/handoffs/{handoff_id}/events

SSE of handoff state changes

Parameters

Name	Type	Required	Description
request_id	`string`	Required	request_id
handoff_id	`string`	Required	handoff_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/credential-requests/<request_id>/handoffs/<handoff_id>/events \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/credential-requests/{request_id}/oauth/start

POST

/api/v1/hands/credential-requests/{request_id}/oauth/start

Start the OAuth connector alternative for a pending request

Parameters

Name	Type	Required	Description
request_id	`string`	Required	request_id
short_code	`string`	Optional	short_code

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/credential-requests/<request_id>/oauth/start \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "authorization_url": "example",
  "provider": "example"
}

POST /api/v1/hands/credential-requests/{request_id}/pause

POST

/api/v1/hands/credential-requests/{request_id}/pause

Pause a credential (fills fail until resumed)

Parameters

Name	Type	Required	Description
request_id	`string`	Required	request_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/credential-requests/<request_id>/pause \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "request_id": "example",
  "task_id": "example",
  "domain": "example",
  "fields": [],
  "reuse": "example",
  "reason": "example"
}

POST /api/v1/hands/credential-requests/{request_id}/provide

POST

/api/v1/hands/credential-requests/{request_id}/provide

Submit the browser-sealed credential (ciphertext only)

Parameters

Name	Type	Required	Description
request_id	`string`	Required	request_id
short_code	`string`	Optional	short_code
key_id	`string`	Required	Key Id
sealed	`string`	Required	Sealed
confirmation	`object`	Optional	Confirmation
handoff_token	`string`	Optional	handoff_token

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/credential-requests/<request_id>/provide \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key_id": "example_key_id",
    "sealed": "example_sealed"
  }'

Response Example

JSON

{
  "request_id": "example",
  "task_id": "example",
  "domain": "example",
  "fields": [],
  "reuse": "example",
  "reason": "example"
}

POST /api/v1/hands/credential-requests/{request_id}/resume

POST

/api/v1/hands/credential-requests/{request_id}/resume

Resume a paused credential

Parameters

Name	Type	Required	Description
request_id	`string`	Required	request_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/credential-requests/<request_id>/resume \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "request_id": "example",
  "task_id": "example",
  "domain": "example",
  "fields": [],
  "reuse": "example",
  "reason": "example"
}

POST /api/v1/hands/credential-requests/{request_id}/revoke

POST

/api/v1/hands/credential-requests/{request_id}/revoke

Revoke: destroy the stored ciphertext, immediate for running tasks

Parameters

Name	Type	Required	Description
request_id	`string`	Required	request_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/credential-requests/<request_id>/revoke \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "request_id": "example",
  "task_id": "example",
  "domain": "example",
  "fields": [],
  "reuse": "example",
  "reason": "example"
}

GET /api/v1/hands/credential-uses/{use_id}

GET

/api/v1/hands/credential-uses/{use_id}

One pending credential use

Parameters

Name	Type	Required	Description
use_id	`string`	Required	use_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/credential-uses/<use_id> \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "request_id": "example",
  "task_id": "example",
  "domain": "example",
  "status": "example",
  "method": "example"
}

POST /api/v1/hands/credential-uses/{use_id}/approve

POST

/api/v1/hands/credential-uses/{use_id}/approve

Approve this use

Parameters

Name	Type	Required	Description
use_id	`string`	Required	use_id
confirmation	`object`	Optional	Confirmation

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/credential-uses/<use_id>/approve \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "request_id": "example",
  "task_id": "example",
  "domain": "example",
  "status": "example",
  "method": "example"
}

POST /api/v1/hands/credential-uses/{use_id}/deny

POST

/api/v1/hands/credential-uses/{use_id}/deny

Deny this use

Parameters

Name	Type	Required	Description
use_id	`string`	Required	use_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/credential-uses/<use_id>/deny \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "request_id": "example",
  "task_id": "example",
  "domain": "example",
  "status": "example",
  "method": "example"
}

POST /api/v1/hands/credential-uses/{use_id}/email-code

POST

/api/v1/hands/credential-uses/{use_id}/email-code

Email a use code

Parameters

Name	Type	Required	Description
use_id	`string`	Required	use_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/credential-uses/<use_id>/email-code \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "sent": true,
  "expires_in": 0
}

POST /api/v1/hands/credential-uses/{use_id}/options

POST

/api/v1/hands/credential-uses/{use_id}/options

Passkey challenge

Parameters

Name	Type	Required	Description
use_id	`string`	Required	use_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/credential-uses/<use_id>/options \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "nonce": "example",
  "challenge": "example",
  "rpId": "example",
  "allowCredentials": [],
  "userVerification": "example",
  "timeout": 0
}

GET /api/v1/hands/credentials

GET

/api/v1/hands/credentials

Dashboard access map: which agent can reach which site

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/credentials \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "agents": [],
  "sites": [],
  "live": [],
  "stream": []
}

GET /api/v1/hands/facts

GET

/api/v1/hands/facts

Get Facts

Parameters

Name	Type	Required	Description
subject	`string`	Optional	subject
key	`string`	Optional	Exact key
prefix	`string`	Optional	Key prefix
version	`integer`	Optional	version
history	`boolean`	Optional	All versions of subject+key, newest firstDefault: `False`
limit	`integer`	Optional	limitDefault: `50`

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/facts \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "facts": []
}

PUT /api/v1/hands/facts

PUT

/api/v1/hands/facts

Put Fact Route

Parameters

Name	Type	Required	Description
subject	`string`	Required	Whose fact: user, org.acme, shop-a ...
key	`string`	Required	Namespaced key, e.g. user.address.home
value	`string`	Required	Value
kind	`string`	Optional	KindDefault: `text`
confidence	`number`	Optional	confidence
as_of	`string`	Optional	as_of
ttl_s	`integer`	Optional	ttl_s
system_of_record	`string`	Optional	system_of_record

Request Example

Bash

curl -X PUT https://api.alterlab.io/api/v1/hands/facts \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "example_subject",
    "key": "example_key",
    "value": "example_value",
    "kind": "example_kind"
  }'

Response Example

JSON

{
  "subject": "example",
  "key": "example",
  "value": "example",
  "kind": "example",
  "status": "example",
  "confidence": 0
}

POST /api/v1/hands/facts/confirm

POST

/api/v1/hands/facts/confirm

Confirm Fact Route

Parameters

Name	Type	Required	Description
subject	`string`	Required	Subject
key	`string`	Required	Key

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/facts/confirm \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "example_subject",
    "key": "example_key"
  }'

Response Example

JSON

{
  "subject": "example",
  "key": "example",
  "value": "example",
  "kind": "example",
  "status": "example",
  "confidence": 0
}

POST /api/v1/hands/graphs

POST

/api/v1/hands/graphs

Create Task Graph

Parameters

Name	Type	Required	Description
credentials	`string[]`	Optional	Credentials
discovered_routes	`object[]`	Optional	Discovered Routes
graph	`object`	Required	Graph
policy	`object`	Required	What policy rules may match on when labelling a graph (same fields as the dry run).
name	`string`	Required	Name

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/graphs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "graph": "...",
    "policy": "...",
    "name": "example_name"
  }'

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/graphs/route

POST

/api/v1/hands/graphs/route

Route Task Graph

Parameters

Name	Type	Required	Description
credentials	`string[]`	Optional	Credentials
discovered_routes	`object[]`	Optional	Discovered Routes
graph	`object`	Required	Graph
policy	`object`	Required	What policy rules may match on when labelling a graph (same fields as the dry run).

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/graphs/route \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "graph": "...",
    "policy": "..."
  }'

Response Example

JSON

{
  "valid": true,
  "errors": [],
  "routes": {},
  "labels": []
}

POST /api/v1/hands/graphs/validate

POST

/api/v1/hands/graphs/validate

Validate Task Graph

Parameters

Name	Type	Required	Description
graph	`object`	Required	Graph
policy	`object`	Required	What policy rules may match on when labelling a graph (same fields as the dry run).

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/graphs/validate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "graph": "...",
    "policy": "..."
  }'

Response Example

JSON

{
  "valid": true,
  "errors": [],
  "graph": {},
  "labels": []
}

POST /api/v1/hands/graphs/{workflow_id}/replan

POST

/api/v1/hands/graphs/{workflow_id}/replan

Task Graph Replan

Parameters

Name	Type	Required	Description
workflow_id	`string`	Required	workflow_id
node	`string`	Required	Node
evidence	`object`	Optional	Evidence
graph	`object`	Required	Graph
policy	`object`	Required	What policy rules may match on when labelling a graph (same fields as the dry run).

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/graphs/<workflow_id>/replan \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "node": "example_node",
    "graph": "...",
    "policy": "..."
  }'

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/graphs/{workflow_id}/replan-request

POST

/api/v1/hands/graphs/{workflow_id}/replan-request

Task Graph Replan Request

Parameters

Name	Type	Required	Description
workflow_id	`string`	Required	workflow_id
node	`string`	Required	Node
evidence	`object`	Optional	Evidence

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/graphs/<workflow_id>/replan-request \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "node": "example_node"
  }'

Response Example

JSON

{
  "graph_version": "example",
  "next_version": "example",
  "failing_node": {},
  "evidence": {},
  "options": [],
  "replans_remaining": 0
}

POST /api/v1/hands/growth-run

POST

/api/v1/hands/growth-run

Create Growth Run

Parameters

Name	Type	Required	Description
rules	`object`	Optional	Rules
drafts	`object`	Optional	Drafts
approvals	`object`	Optional	Approvals
accounts	`object[]`	Optional	Accounts

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/growth-run \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/growth-run/scoreboard/public

GET

/api/v1/hands/growth-run/scoreboard/public

Public Growth Scoreboard

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/growth-run/scoreboard/public \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/growth-run/{run_id}/detail

GET

/api/v1/hands/growth-run/{run_id}/detail

Growth Run Detail

Parameters

Name	Type	Required	Description
run_id	`string`	Required	run_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/growth-run/<run_id>/detail \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/growth-run/{run_id}/scoreboard

POST

/api/v1/hands/growth-run/{run_id}/scoreboard

Publish Growth Scoreboard

Parameters

Name	Type	Required	Description
run_id	`string`	Required	run_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/growth-run/<run_id>/scoreboard \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/handoffs/open

POST

/api/v1/hands/handoffs/open

Open a handoff on the phone (same account, once)

Parameters

Name	Type	Required	Description
token	`string`	Required	Token

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/handoffs/open \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "example_token"
  }'

Response Example

JSON

{
  "request_id": "example"
}

POST /api/v1/hands/identities

POST

/api/v1/hands/identities

Post Identity

Parameters

Name	Type	Required	Description
name	`string`	Required	Name
profile	`object`	Optional	Profile

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/identities \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "example_name"
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/identities

GET

/api/v1/hands/identities

List Identities

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/identities \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

DELETE /api/v1/hands/identities/{identity_id}

DELETE

/api/v1/hands/identities/{identity_id}

Remove Identity

Parameters

Name	Type	Required	Description
identity_id	`string`	Required	identity_id

Request Example

Bash

curl -X DELETE https://api.alterlab.io/api/v1/hands/identities/<identity_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

PUT /api/v1/hands/identities/{identity_id}/accounts

PUT

/api/v1/hands/identities/{identity_id}/accounts

Put Account

Parameters

Name	Type	Required	Description
identity_id	`string`	Required	identity_id
target	`string`	Required	Target
session_id	`string`	Required	Session Id

Request Example

Bash

curl -X PUT https://api.alterlab.io/api/v1/hands/identities/<identity_id>/accounts \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "example_target",
    "session_id": "example_session_id"
  }'

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/identities/{identity_id}/sessions

POST

/api/v1/hands/identities/{identity_id}/sessions

Attach Session

Parameters

Name	Type	Required	Description
identity_id	`string`	Required	identity_id
session_id	`string`	Required	Session Id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/identities/<identity_id>/sessions \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "example_session_id"
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/kill-switch

GET

/api/v1/hands/kill-switch

Kill Switch Status

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/kill-switch \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "active": true
}

DELETE /api/v1/hands/kill-switch

DELETE

/api/v1/hands/kill-switch

Release Kill Switch

Request Example

Bash

curl -X DELETE https://api.alterlab.io/api/v1/hands/kill-switch \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "active": true
}

POST /api/v1/hands/launch-campaign

POST

/api/v1/hands/launch-campaign

Create Launch Campaign

Parameters

Name	Type	Required	Description
launch_day	`string`	Required	Launch Day
rules	`object`	Optional	Rules
drafts	`object`	Optional	Drafts
accounts	`object[]`	Optional	Accounts

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/launch-campaign \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "launch_day": "example_launch_day"
  }'

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/launch-campaign/reply-decision

POST

/api/v1/hands/launch-campaign/reply-decision

Launch Campaign Reply Decision

Parameters

Name	Type	Required	Description
channel	`string`	Required	Channel
text	`string`	Required	Text
accounts	`object[]`	Optional	Accounts
dm_recipients	`integer`	Optional	Dm RecipientsDefault: `0`
paid	`boolean`	Optional	PaidDefault: `False`
disclosed	`boolean`	Optional	DisclosedDefault: `False`

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/launch-campaign/reply-decision \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "example_channel",
    "text": "example_text",
    "dm_recipients": 0,
    "paid": false
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/launch-campaign/results/public

GET

/api/v1/hands/launch-campaign/results/public

Public Launch Results

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/launch-campaign/results/public \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/launch-campaign/{run_id}/conversations

POST

/api/v1/hands/launch-campaign/{run_id}/conversations

Open Launch Campaign Conversation

Parameters

Name	Type	Required	Description
run_id	`string`	Required	run_id
counterparty	`object`	Required	Counterparty
channel	`string`	Required	Channel
goal	`object`	Required	Goal
limits	`object`	Optional	Set by the user at creation; nothing an inbound message says can change them.
persona	`object`	Optional	Persona
sender	`string`	Optional	sender
thread_ref	`string`	Optional	thread_ref
message_budget	`integer`	Optional	Message BudgetDefault: `10`
min_gap_s	`integer`	Optional	Min Gap SDefault: `60`
follow_up_delay_s	`integer`	Optional	follow_up_delay_s
follow_up_text	`string`	Optional	follow_up_text

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/launch-campaign/<run_id>/conversations \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "counterparty": "...",
    "channel": "example_channel",
    "goal": "..."
  }'

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/launch-campaign/{run_id}/kill

POST

/api/v1/hands/launch-campaign/{run_id}/kill

Kill Launch Campaign

Parameters

Name	Type	Required	Description
run_id	`string`	Required	run_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/launch-campaign/<run_id>/kill \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/launch-campaign/{run_id}/results

POST

/api/v1/hands/launch-campaign/{run_id}/results

Record Launch Campaign Results

Parameters

Name	Type	Required	Description
run_id	`string`	Required	run_id
metrics	`object`	Optional	Metrics
utm_clicks	`object`	Optional	Utm Clicks

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/launch-campaign/<run_id>/results \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/live-view

POST

/api/v1/hands/live-view

Start a remote-browser sign-in

Parameters

Name	Type	Required	Description
domain	`string`	Required	Domain
domain_set	`string[]`	Optional	domain_set
name	`string`	Optional	NameDefault: `Remote sign-in`
capture_context	`object`	Required	Browser telemetry (user_agent, locale, timezone, ...) pinning the identity

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/live-view \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example_domain",
    "name": "example_name",
    "capture_context": "..."
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/live-view/{live_view_id}

GET

/api/v1/hands/live-view/{live_view_id}

Poll a remote-browser sign-in

Parameters

Name	Type	Required	Description
live_view_id	`string`	Required	live_view_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/live-view/<live_view_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "live_view_id": "example",
  "status": "example",
  "expires_at": "example",
  "session_id": "example"
}

DELETE /api/v1/hands/live-view/{live_view_id}

DELETE

/api/v1/hands/live-view/{live_view_id}

Cancel a remote-browser sign-in

Parameters

Name	Type	Required	Description
live_view_id	`string`	Required	live_view_id

Request Example

Bash

curl -X DELETE https://api.alterlab.io/api/v1/hands/live-view/<live_view_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/local/tasks

GET

/api/v1/hands/local/tasks

Local Tasks

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/local/tasks \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/permissions

GET

/api/v1/hands/permissions

List Permissions

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/permissions \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/permissions

POST

/api/v1/hands/permissions

Create Permission

Parameters

Name	Type	Required	Description
site	`string`	Required	Registered domain
action_class	`"click" \| "form_input" \| "upload" \| "any_write"`	Required	Action Class
daily_limit	`integer`	Required	Daily Limit
recipe	`string`	Optional	recipe

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/permissions \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "site": "example_site",
    "action_class": "...",
    "daily_limit": 0
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/permissions/audit

GET

/api/v1/hands/permissions/audit

Permission Audit

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/permissions/audit \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

DELETE /api/v1/hands/permissions/{permission_id}

DELETE

/api/v1/hands/permissions/{permission_id}

Revoke Permission

Parameters

Name	Type	Required	Description
permission_id	`string`	Required	permission_id

Request Example

Bash

curl -X DELETE https://api.alterlab.io/api/v1/hands/permissions/<permission_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/policies

GET

/api/v1/hands/policies

Get Policies

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/policies \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "account": "example",
  "keys": []
}

PUT /api/v1/hands/policies

PUT

/api/v1/hands/policies

Put Policies

Parameters

Name	Type	Required	Description
rules	`object[]`	Optional	Rules
key_id	`string`	Optional	key_id

Request Example

Bash

curl -X PUT https://api.alterlab.io/api/v1/hands/policies \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "key_id": "example",
  "version": 0,
  "rules": [],
  "created_at": "example"
}

POST /api/v1/hands/policies/evaluate

POST

/api/v1/hands/policies/evaluate

Evaluate Policy

Parameters

Name	Type	Required	Description
domains	`string[]`	Required	Domains
actions	`object[]`	Required	Actions
risk_classes	`string[]`	Optional	risk_classes
recipe	`string`	Optional	recipe
facts_verified	`"all" \| "any" \| "none"`	Optional	Facts VerifiedDefault: `none`
amount	`number`	Optional	amount
currency	`string`	Optional	currency
counterparty_class	`string`	Optional	counterparty_class
task_label	`string`	Optional	task_label
key_id	`string`	Optional	key_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/policies/evaluate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": [],
    "actions": [],
    "facts_verified": "..."
  }'

Response Example

JSON

{
  "decision": "example",
  "rule_ids": [],
  "reasons": [],
  "actions": []
}

POST /api/v1/hands/policies/revoke

POST

/api/v1/hands/policies/revoke

Revoke Policies

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/policies/revoke \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "account": "example",
  "keys": []
}

GET /api/v1/hands/preferences

GET

/api/v1/hands/preferences

List Standing Preferences

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/preferences \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "facts": []
}

PUT /api/v1/hands/preferences

PUT

/api/v1/hands/preferences

Put Standing Preference

Parameters

Name	Type	Required	Description
name	`string`	Required	Name
value	`string`	Required	Value

Request Example

Bash

curl -X PUT https://api.alterlab.io/api/v1/hands/preferences \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "example_name",
    "value": "example_value"
  }'

Response Example

JSON

{
  "subject": "example",
  "key": "example",
  "value": "example",
  "kind": "example",
  "status": "example",
  "confidence": 0
}

POST /api/v1/hands/preview

POST

/api/v1/hands/preview

Create Preview

Parameters

Name	Type	Required	Description
goal	`string`	Required	Goal
public_url	`string`	Optional	public_url

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/preview \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "example_goal"
  }'

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/quote

POST

/api/v1/hands/quote

Quote Task

Parameters

Name	Type	Required	Description
goal	`string`	Optional	goal
plan_hash	`string`	Optional	plan_hash
targets	`integer`	Optional	Number of sites or itemsDefault: `1`
browser_seconds	`integer`	Optional	browser_seconds
lookups	`integer`	Optional	lookups
proxy_bytes	`integer`	Optional	Proxy BytesDefault: `0`
browse_only	`boolean`	Optional	Browse OnlyDefault: `False`

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/quote \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": 1
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/receipt-keys

GET

/api/v1/hands/receipt-keys

Hands Receipt Keys

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/receipt-keys \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "schema_version": 0,
  "keys": []
}

GET /api/v1/hands/replays

GET

/api/v1/hands/replays

Public recorded-run replays: only approved runs whose receipt verifies

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/replays \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "v": 0,
  "runs": []
}

GET /api/v1/hands/replays/{run_id}/receipt

GET

/api/v1/hands/replays/{run_id}/receipt

Public receipt check for a published replay (verify_url target)

Parameters

Name	Type	Required	Description
run_id	`string`	Required	run_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/replays/<run_id>/receipt \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "verdict": "example",
  "signature_valid": true,
  "key_version": "example",
  "bundle_hash": "example",
  "recorded_at": "example"
}

GET /api/v1/hands/requests/pending

GET

/api/v1/hands/requests/pending

List Pending

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/requests/pending \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/requirements

POST

/api/v1/hands/requirements

Requirements

Parameters

Name	Type	Required	Description
goal	`string`	Required	Goal
target	`object`	Optional	What the goal acts on: a page, a named entity, or nothing in particular.
page_schema_id	`string`	Optional	page_schema_id
page_schema	`object`	Optional	What the current page asks of an agent (#39813); bounded, with a structural hash.
context_refs	`string[]`	Optional	Connected sources the user has (e.g. calendar, mail, drive, stripe)

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/requirements \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "example_goal"
  }'

Response Example

JSON

{
  "requirements": [],
  "unmapped": [],
  "plan_hash": "example",
  "page_schema_id": "example",
  "untrusted_content": "example"
}

GET /api/v1/hands/risk-disclosure

GET

/api/v1/hands/risk-disclosure

Get Risk Disclosure

Parameters

Name	Type	Required	Description
site_class	`string`	Required	site_class

Request Example

Bash

curl -X GET 'https://api.alterlab.io/api/v1/hands/risk-disclosure?site_class=<site_class>' \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "site_class": "example",
  "version": 0,
  "text": "example",
  "acknowledged": true
}

POST /api/v1/hands/risk-disclosure/ack

POST

/api/v1/hands/risk-disclosure/ack

Acknowledge Risk Disclosure

Parameters

Name	Type	Required	Description
site_class	`string`	Required	Site Class
version	`integer`	Required	Disclosure version the user was shown

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/risk-disclosure/ack \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "site_class": "example_site_class",
    "version": 0
  }'

Response Example

JSON

{
  "site_class": "example",
  "version": 0,
  "text": "example",
  "acknowledged": true
}

POST /api/v1/hands/routes

POST

/api/v1/hands/routes

Routes

Parameters

Name	Type	Required	Description
goal	`string`	Required	Goal
entity	`object`	Required	RouteEntity
constraints	`object`	Optional	RouteConstraints
evidence	`object[]`	Optional	Evidence
connected_evidence	`object[]`	Optional	Connected Evidence
context_refs	`string[]`	Optional	Context Refs

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/routes \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "example_goal",
    "entity": "..."
  }'

Response Example

JSON

{
  "goal": "example",
  "entity": {},
  "routes": [],
  "conflicts": [],
  "intro_note": "example",
  "discovery_plan": []
}

POST /api/v1/hands/runs

POST

/api/v1/hands/runs

Create Delegated Run Route

Parameters

Name	Type	Required	Description
label	`string`	Required	Label
template	`object`	Optional	Template
targets	`object`	Required	Where a run's targets come from: a list, a fact query, or a fan-out over accounts.
schedule_interval_s	`integer`	Optional	schedule_interval_s
followup_after_s	`integer`	Optional	Followup After SDefault: `86400`
max_followups	`integer`	Optional	Max FollowupsDefault: `3`

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/runs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "example_label",
    "targets": "...",
    "followup_after_s": 86400
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/runs

GET

/api/v1/hands/runs

List Runs

Parameters

Name	Type	Required	Description
limit	`integer`	Optional	limitDefault: `50`

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/runs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "runs": []
}

POST /api/v1/hands/runs/stop-all

POST

/api/v1/hands/runs/stop-all

Stop All Runs

Parameters

Name	Type	Required	Description
scope	`"user" \| "agent_key"`	Optional	ScopeDefault: `user`
api_key_id	`string`	Optional	api_key_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/runs/stop-all \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "..."
  }'

Response Example

JSON

{
  "scope": "example",
  "stopped": [],
  "kill_switch": true
}

POST /api/v1/hands/runs/targets/{target_id}/answer

POST

/api/v1/hands/runs/targets/{target_id}/answer

Answer Target

Parameters

Name	Type	Required	Description
target_id	`string`	Required	target_id
approved	`boolean`	Required	Approved

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/runs/targets/<target_id>/answer \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "approved": false
  }'

Response Example

JSON

{
  "id": "example",
  "label": "example",
  "status": "example",
  "parent_run_id": "example",
  "period_key": "example",
  "schedule_interval_s": "example"
}

POST /api/v1/hands/runs/wake

POST

/api/v1/hands/runs/wake

Wake Targets

Parameters

Name	Type	Required	Description
type	`"message" \| "trigger" \| "webhook"`	Optional	TypeDefault: `webhook`
ref	`string`	Required	Ref
payload	`object`	Optional	Payload

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/runs/wake \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "...",
    "ref": "example_ref"
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/runs/{run_id}

GET

/api/v1/hands/runs/{run_id}

Get Delegated Run

Parameters

Name	Type	Required	Description
run_id	`string`	Required	run_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/runs/<run_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "label": "example",
  "status": "example",
  "parent_run_id": "example",
  "period_key": "example",
  "schedule_interval_s": "example"
}

POST /api/v1/hands/runs/{run_id}/advance

POST

/api/v1/hands/runs/{run_id}/advance

Advance Run

Parameters

Name	Type	Required	Description
run_id	`string`	Required	run_id
facts	`object[]`	Optional	Facts
act	`object`	Optional	ActRequest
finish	`boolean`	Optional	FinishDefault: `False`

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/runs/<run_id>/advance \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "finish": false
  }'

Response Example

JSON

{
  "id": "example",
  "mode": "example",
  "state": "example",
  "blocked_reason": "example",
  "goal": "example",
  "target": {}
}

POST /api/v1/hands/runs/{run_id}/answer

POST

/api/v1/hands/runs/{run_id}/answer

Answer Delegation Run

Parameters

Name	Type	Required	Description
run_id	`string`	Required	run_id
request_id	`string`	Required	Request Id
decision	`"approve" \| "deny"`	Optional	decision
answer	`string`	Optional	answer
via	`"api" \| "mcp" \| "extension" \| "dashboard" \| "email" \| "telegram"`	Optional	ViaDefault: `api`

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/runs/<run_id>/answer \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "example_request_id",
    "via": "..."
  }'

Response Example

JSON

{
  "id": "example",
  "mode": "example",
  "state": "example",
  "blocked_reason": "example",
  "goal": "example",
  "target": {}
}

POST /api/v1/hands/runs/{run_id}/cancel

POST

/api/v1/hands/runs/{run_id}/cancel

Cancel Delegated Run

Parameters

Name	Type	Required	Description
run_id	`string`	Required	run_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/runs/<run_id>/cancel \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "label": "example",
  "status": "example",
  "parent_run_id": "example",
  "period_key": "example",
  "schedule_interval_s": "example"
}

GET /api/v1/hands/runs/{run_id}/events

GET

/api/v1/hands/runs/{run_id}/events

Run Events

Parameters

Name	Type	Required	Description
run_id	`string`	Required	run_id
after	`integer`	Optional	afterDefault: `0`

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/runs/<run_id>/events \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/runs/{run_id}/publish

POST

/api/v1/hands/runs/{run_id}/publish

Publish a completed run as a redacted, receipt-verified replay (owner-approved)

Parameters

Name	Type	Required	Description
run_id	`string`	Required	run_id
approve	`boolean`	Required	Must be true: the owner approves publishing this run
title	`string`	Optional	title

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/runs/<run_id>/publish \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "approve": false
  }'

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/runs/{run_id}/share

POST

/api/v1/hands/runs/{run_id}/share

Publish a completed run as a public replay page (owner-approved, republishable)

Parameters

Name	Type	Required	Description
run_id	`string`	Required	run_id
title	`string`	Optional	title
indexable	`boolean`	Optional	IndexableDefault: `False`
approve	`boolean`	Required	Must be true: the owner approves this public page

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/runs/<run_id>/share \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "indexable": false,
    "approve": false
  }'

Response Example

JSON

{
  "v": 0,
  "slug": "example",
  "title": "example",
  "task_class": "example"
}

DELETE /api/v1/hands/runs/{run_id}/share

DELETE

/api/v1/hands/runs/{run_id}/share

Unpublish a shared run: its public link returns 404

Parameters

Name	Type	Required	Description
run_id	`string`	Required	run_id

Request Example

Bash

curl -X DELETE https://api.alterlab.io/api/v1/hands/runs/<run_id>/share \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/runs/{run_id}/share/preview

POST

/api/v1/hands/runs/{run_id}/share/preview

Preview the exact public page a completed run would publish (nothing is stored)

Parameters

Name	Type	Required	Description
run_id	`string`	Required	run_id
title	`string`	Optional	title
indexable	`boolean`	Optional	IndexableDefault: `False`

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/runs/<run_id>/share/preview \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "indexable": false
  }'

Response Example

JSON

{
  "v": 0,
  "slug": "example",
  "title": "example",
  "task_class": "example"
}

GET /api/v1/hands/sessions

GET

/api/v1/hands/sessions

List session handles with health and scopes

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/sessions \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

DELETE /api/v1/hands/sessions/{session_id}

DELETE

/api/v1/hands/sessions/{session_id}

Revoke a session handle

Parameters

Name	Type	Required	Description
session_id	`string`	Required	session_id

Request Example

Bash

curl -X DELETE https://api.alterlab.io/api/v1/hands/sessions/<session_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/sessions/{session_id}/clear-risk

POST

/api/v1/hands/sessions/{session_id}/clear-risk

Clear Session Risk

Parameters

Name	Type	Required	Description
session_id	`string`	Required	session_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/sessions/<session_id>/clear-risk \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "session_id": "example",
  "cleared_alerts": 0,
  "status": "example"
}

GET /api/v1/hands/share-funnel

GET

/api/v1/hands/share-funnel

Your share funnel: shares, views, remixes, signups and K-factor

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/share-funnel \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/shares/{slug}

GET

/api/v1/hands/shares/{slug}

Public shared run page data (no auth); unpublished or unverifiable slugs are 404

Parameters

Name	Type	Required	Description
slug	`string`	Required	slug

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/shares/<slug> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "v": 0,
  "slug": "example",
  "title": "example",
  "task_class": "example"
}

GET /api/v1/hands/shares/{slug}/clip.gif

GET

/api/v1/hands/shares/{slug}/clip.gif

Animated GIF of the timeline, rendered from the run events

Parameters

Name	Type	Required	Description
slug	`string`	Required	slug

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/shares/<slug>/clip.gif \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/shares/{slug}/og

GET

/api/v1/hands/shares/{slug}/og

Text for the share's OG card, generated from the run events

Parameters

Name	Type	Required	Description
slug	`string`	Required	slug

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/shares/<slug>/og \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/shares/{slug}/receipt

GET

/api/v1/hands/shares/{slug}/receipt

Public receipt check for a shared run (verify_url target)

Parameters

Name	Type	Required	Description
slug	`string`	Required	slug

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/shares/<slug>/receipt \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/shares/{slug}/remix

POST

/api/v1/hands/shares/{slug}/remix

Start a remix: the goal as a template to run with your own accounts (no signup)

Parameters

Name	Type	Required	Description
slug	`string`	Required	slug

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/shares/<slug>/remix \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/shares/{slug}/remix/complete

POST

/api/v1/hands/shares/{slug}/remix/complete

Record a finished remix run; a new user's completion credits the sharer's referral

Parameters

Name	Type	Required	Description
slug	`string`	Required	slug
run_id	`string`	Required	The viewer's own completed run started from the template

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/shares/<slug>/remix/complete \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "run_id": "example_run_id"
  }'

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/skills

POST

/api/v1/hands/skills

Promote Skill

Parameters

Name	Type	Required	Description
workflow_id	`string`	Required	Stored task graph of the confirmed run
run_id	`string`	Required	The completed workflow run that confirmed it
name	`string`	Required	Name
description	`string`	Optional	description
bindings	`object[]`	Optional	Bindings
selectors	`object`	Optional	Selectors
schema_hashes	`object`	Optional	Schema Hashes

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/skills \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "example_workflow_id",
    "run_id": "example_run_id",
    "name": "example_name"
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/skills

GET

/api/v1/hands/skills

List Skills

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/skills \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "items": []
}

POST /api/v1/hands/skills/match

POST

/api/v1/hands/skills/match

Match Skills

Parameters

Name	Type	Required	Description
goal	`string`	Required	Goal
site	`string`	Required	Site

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/skills/match \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "example_goal",
    "site": "example_site"
  }'

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/skills/{workflow_id}/repair

POST

/api/v1/hands/skills/{workflow_id}/repair

Repair Skill

Parameters

Name	Type	Required	Description
workflow_id	`string`	Required	workflow_id
node	`string`	Required	Node
selectors	`string[]`	Required	Selectors
schema_hash	`string`	Optional	schema_hash
preview_task_id	`string`	Required	Preview-mode task that validated the patch

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/skills/<workflow_id>/repair \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "node": "example_node",
    "selectors": [],
    "preview_task_id": "example_preview_task_id"
  }'

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/tasks

POST

/api/v1/hands/tasks

Create Task

Parameters

Name	Type	Required	Description
start_url	`string`	Required	Start Url
session_id	`string`	Optional	session_id
identity_id	`string`	Optional	identity_id
mode	`"read" \| "write" \| "preview"`	Optional	'preview' explores and fills in a throwaway context with no side effects: non-GET requests are aborted and submit, message, money and legal_attestation actions return preview_blockedDefault: `read`
execution	`"remote" \| "local"`	Optional	'local' runs actions in the user's own browser via the extension; no session material is uploadedDefault: `remote`
ttl_s	`integer`	Optional	Ttl SDefault: `900`
limits	`object`	Optional	TaskLimits
allowed_domains	`string[]`	Optional	allowed_domains
instruction	`string`	Optional	instruction
plan_hash	`string`	Optional	plan_hash
fact_refs	`object[]`	Optional	fact_refs

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/tasks \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start_url": "example_start_url",
    "mode": "...",
    "execution": "..."
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/tasks

GET

/api/v1/hands/tasks

List Tasks

Parameters

Name	Type	Required	Description
limit	`integer`	Optional	limitDefault: `25`
cursor	`string`	Optional	cursor
status	`string`	Optional	status

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/tasks \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "items": [],
  "next_cursor": "example"
}

GET /api/v1/hands/tasks/{task_id}

GET

/api/v1/hands/tasks/{task_id}

Get Task

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/tasks/<task_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "status": "example",
  "mode": "example",
  "execution": "example",
  "failure_reason": "example",
  "start_url": "example"
}

DELETE /api/v1/hands/tasks/{task_id}

DELETE

/api/v1/hands/tasks/{task_id}

Close Task

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id

Request Example

Bash

curl -X DELETE https://api.alterlab.io/api/v1/hands/tasks/<task_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "status": "example",
  "mode": "example",
  "execution": "example",
  "failure_reason": "example",
  "start_url": "example"
}

POST /api/v1/hands/tasks/{task_id}/act

POST

/api/v1/hands/tasks/{task_id}/act

Act

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id
actions	`object[]`	Required	Actions
approval_ref	`string`	Optional	approval_ref
budget_kind	`"write" \| "post" \| "message" \| "application"`	Optional	budget_kind
recipe	`string`	Optional	recipe
provenance	`object`	Optional	Where a write intent came from; recorded in the audit log for every executed write.
bindings	`object[]`	Optional	bindings
require_verified	`boolean`	Optional	Refuse any fill/type/select value that has no binding (verification gate)Default: `False`
intent	`object`	Optional	Context the policy engine matches on (#39818). The amount is never taken from the caller: ''amount_fact'' points at a price fact that must verify at act time, and only then can a ''money'' rule auto-approve.

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/tasks/<task_id>/act \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": []
  }'

Response Example

JSON

{
  "task_id": "example",
  "step_id": "example",
  "status": "example",
  "failure_reason": "example",
  "action_results": [],
  "pending_request": "example"
}

POST /api/v1/hands/tasks/{task_id}/answer

POST

/api/v1/hands/tasks/{task_id}/answer

Answer

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id
request_id	`string`	Required	Request Id
decision	`"approve" \| "deny"`	Optional	decision
answer	`string`	Optional	answer
via	`"api" \| "mcp" \| "extension" \| "dashboard" \| "email" \| "telegram"`	Optional	ViaDefault: `api`

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/tasks/<task_id>/answer \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "example_request_id",
    "via": "..."
  }'

Response Example

JSON

{
  "id": "example",
  "task_id": "example",
  "kind": "example",
  "status": "example",
  "prompt": "example",
  "choices": "example"
}

GET /api/v1/hands/tasks/{task_id}/events

GET

/api/v1/hands/tasks/{task_id}/events

Task Events

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id
after	`integer`	Optional	after

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/tasks/<task_id>/events \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/tasks/{task_id}/files

POST

/api/v1/hands/tasks/{task_id}/files

Upload File

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id
filename	`string`	Required	Filename
content_type	`string`	Optional	Content TypeDefault: `application/octet-stream`
content_base64	`string`	Required	Content Base64

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/tasks/<task_id>/files \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "example_filename",
    "content_type": "example_content_type",
    "content_base64": "example_content_base64"
  }'

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/tasks/{task_id}/human

POST

/api/v1/hands/tasks/{task_id}/human

Ask Human

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id
reason	`"founder_video" \| "signature" \| "legal_attestation" \| "live_interview"`	Required	Reason
prompt	`string`	Required	Prompt

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/tasks/<task_id>/human \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "...",
    "prompt": "example_prompt"
  }'

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/tasks/{task_id}/human/{request_id}/complete

POST

/api/v1/hands/tasks/{task_id}/human/{request_id}/complete

Complete Human

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id
request_id	`string`	Required	request_id
attested	`boolean`	Required	The user confirms they did this step themselves
artifact_base64	`string`	Optional	artifact_base64
filename	`string`	Optional	filename
content_type	`string`	Optional	content_type

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/tasks/<task_id>/human/<request_id>/complete \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "attested": false
  }'

Response Example

JSON

{
  "id": "example",
  "task_id": "example",
  "kind": "example",
  "status": "example",
  "prompt": "example",
  "choices": "example"
}

GET /api/v1/hands/tasks/{task_id}/local/next

GET

/api/v1/hands/tasks/{task_id}/local/next

Local Next

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/tasks/<task_id>/local/next \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "task_id": "example",
  "status": "example",
  "step": "example"
}

POST /api/v1/hands/tasks/{task_id}/local/result

POST

/api/v1/hands/tasks/{task_id}/local/result

Local Result

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id
step_id	`string`	Required	Step Id
status	`string`	Optional	StatusDefault: `running`
failure_reason	`string`	Optional	failure_reason
action_results	`object[]`	Optional	Action Results
observation	`object`	Optional	observation

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/tasks/<task_id>/local/result \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "step_id": "example_step_id",
    "status": "example_status"
  }'

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/tasks/{task_id}/local/stop

POST

/api/v1/hands/tasks/{task_id}/local/stop

Local Stop

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/tasks/<task_id>/local/stop \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "status": "example",
  "mode": "example",
  "execution": "example",
  "failure_reason": "example",
  "start_url": "example"
}

GET /api/v1/hands/tasks/{task_id}/observe

GET

/api/v1/hands/tasks/{task_id}/observe

Observe

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/tasks/<task_id>/observe \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "task_id": "example",
  "status": "example",
  "url": "example",
  "observation": "example",
  "untrusted_content": "example"
}

PUT /api/v1/hands/tasks/{task_id}/outcome

PUT

/api/v1/hands/tasks/{task_id}/outcome

Declare what resolved means for a task

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id
definition	`object`	Required	What resolved means and how to observe it.
deadline_s	`integer`	Required	Deadline S
check_interval_s	`integer`	Optional	Check Interval SDefault: `3600`

Request Example

Bash

curl -X PUT https://api.alterlab.io/api/v1/hands/tasks/<task_id>/outcome \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": "...",
    "deadline_s": 0,
    "check_interval_s": 3600
  }'

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/tasks/{task_id}/outcome/observations

POST

/api/v1/hands/tasks/{task_id}/outcome/observations

Record an observation of a task's outcome

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id
source	`"api" \| "mail" \| "page" \| "ledger" \| "confirmation_page"`	Required	Source
value	`string`	Required	Value
evidence	`object`	Optional	evidence

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/tasks/<task_id>/outcome/observations \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "...",
    "value": "example_value"
  }'

Response Example

JSON

{
  "task_id": "example",
  "state": "example",
  "definition": {},
  "deadline_at": "example",
  "next_check_at": "example",
  "followup_count": 0
}

POST /api/v1/hands/tasks/{task_id}/pause

POST

/api/v1/hands/tasks/{task_id}/pause

Pause Task

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/tasks/<task_id>/pause \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "task_id": "example",
  "status": "example",
  "paused_by": "example"
}

POST /api/v1/hands/tasks/{task_id}/questions

POST

/api/v1/hands/tasks/{task_id}/questions

Ask User

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id
kind	`"question" \| "connect"`	Optional	KindDefault: `question`
prompt	`string`	Required	Prompt
choices	`string[]`	Optional	choices

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/tasks/<task_id>/questions \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "...",
    "prompt": "example_prompt"
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/tasks/{task_id}/requests

GET

/api/v1/hands/tasks/{task_id}/requests

List Task Requests

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/tasks/<task_id>/requests \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/tasks/{task_id}/resume

POST

/api/v1/hands/tasks/{task_id}/resume

Resume Task

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/tasks/<task_id>/resume \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "task_id": "example",
  "status": "example",
  "paused_by": "example"
}

POST /api/v1/hands/tasks/{task_id}/schema

POST

/api/v1/hands/tasks/{task_id}/schema

Page Schema

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/tasks/<task_id>/schema \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "task_id": "example",
  "status": "example",
  "url": "example",
  "page_schema": "example",
  "untrusted_content": "example"
}

POST /api/v1/hands/tasks/{task_id}/steer

POST

/api/v1/hands/tasks/{task_id}/steer

Steer Task

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id
instruction	`string`	Required	Instruction

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/tasks/<task_id>/steer \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "example_instruction"
  }'

Response Example

JSON

{
  "id": "example",
  "text": "example",
  "at": "example",
  "by": "example",
  "trusted": true
}

POST /api/v1/hands/tasks/{task_id}/stop

POST

/api/v1/hands/tasks/{task_id}/stop

Stop Task

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/tasks/<task_id>/stop \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "task_id": "example",
  "status": "example",
  "paused_by": "example"
}

POST /api/v1/hands/tasks/{task_id}/takeover

POST

/api/v1/hands/tasks/{task_id}/takeover

Takeover Task

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/tasks/<task_id>/takeover \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/tasks/{task_id}/timeline

GET

/api/v1/hands/tasks/{task_id}/timeline

One timeline per task: declaration, observations, state changes, follow-up

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/tasks/<task_id>/timeline \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "task_id": "example",
  "outcome": "example",
  "events": []
}

POST /api/v1/hands/tasks/{task_id}/vision/act

POST

/api/v1/hands/tasks/{task_id}/vision/act

Vision Act

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id
x	`number`	Required	CSS pixels from the viewport origin
y	`number`	Required	Y
selector	`string`	Optional	selector
expect	`object`	Optional	Read-back expectation: {{'text': 'shown after'}} or {{'changed': true}}
approval_ref	`string`	Optional	approval_ref
recipe	`string`	Optional	recipe

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/tasks/<task_id>/vision/act \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "x": 0,
    "y": 0
  }'

Response Example

JSON

{
  "task_id": "example",
  "step_id": "example",
  "status": "example",
  "failure_reason": "example",
  "action_results": [],
  "pending_request": "example"
}

POST /api/v1/hands/tasks/{task_id}/vision/capture

POST

/api/v1/hands/tasks/{task_id}/vision/capture

Vision Capture

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id
selector	`string`	Optional	selector

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/tasks/<task_id>/vision/capture \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "task_id": "example",
  "status": "example",
  "failure_reason": "example",
  "capture": "example",
  "vision": "example",
  "untrusted_content": "example"
}

GET /api/v1/hands/tasks/{task_id}/watch

GET

/api/v1/hands/tasks/{task_id}/watch

Watch Run

Parameters

Name	Type	Required	Description
task_id	`string`	Required	task_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/tasks/<task_id>/watch \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "task_id": "example",
  "status": "example",
  "paused_by": "example",
  "pages": 0,
  "actions": 0,
  "events": []
}

POST /api/v1/hands/triggers

POST

/api/v1/hands/triggers

Create Trigger

Parameters

Name	Type	Required	Description
label	`string`	Required	Label
source_type	`string`	Required	Source Type
source_ref	`string`	Optional	source_ref
condition	`object`	Optional	Fires when the observed fact value satisfies ''op threshold''; verified before acting.
run_template	`object`	Required	RunTemplate
rate_limit_per_hour	`integer`	Optional	Rate Limit Per HourDefault: `4`
spend_limit	`number`	Optional	spend_limit
breaker_threshold	`integer`	Optional	Breaker ThresholdDefault: `3`
interval_s	`integer`	Optional	interval_s

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/triggers \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "example_label",
    "source_type": "example_source_type",
    "run_template": "..."
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/triggers

GET

/api/v1/hands/triggers

List Triggers

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/triggers \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "triggers": []
}

POST /api/v1/hands/triggers/{trigger_id}/fire

POST

/api/v1/hands/triggers/{trigger_id}/fire

Fire Trigger

Parameters

Name	Type	Required	Description
trigger_id	`string`	Required	trigger_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/triggers/<trigger_id>/fire \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/hands/triggers/{trigger_id}/firings

GET

/api/v1/hands/triggers/{trigger_id}/firings

List Firings

Parameters

Name	Type	Required	Description
trigger_id	`string`	Required	trigger_id
limit	`integer`	Optional	limitDefault: `50`

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/hands/triggers/<trigger_id>/firings \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "firings": []
}

POST /api/v1/hands/triggers/{trigger_id}/webhook

POST

/api/v1/hands/triggers/{trigger_id}/webhook

Trigger Webhook

Parameters

Name	Type	Required	Description
trigger_id	`string`	Required	trigger_id
x-trigger-token	`string`	Optional	x-trigger-token
value	`string`	Optional	Value
step_id	`string`	Optional	step_id
job_id	`string`	Optional	job_id
url	`string`	Optional	url
fetched_at	`string`	Optional	fetched_at
tier	`string`	Optional	tier
evidence	`string`	Optional	Evidence

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/triggers/<trigger_id>/webhook \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/hands/triggers/{trigger_id}/{action}

POST

/api/v1/hands/triggers/{trigger_id}/{action}

Trigger Action

Parameters

Name	Type	Required	Description
trigger_id	`string`	Required	trigger_id
action	`string`	Required	action

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/hands/triggers/<trigger_id>/<action> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "label": "example",
  "source_type": "example",
  "source_ref": "example",
  "condition": "example",
  "run_template": {}
}

Last updated: June 2026