Address

Reference

Approvals

What an agent asked that only a person may do, and the sends a person wanted to see first.

Markdown

Calls go to https://address.seleya.ai/api. A refusal is {"error": {"code", "message"}} with its status; every code is in Errors.

Waiting for a person

GET /v1/approvals

Called with a key or a person signed in.

What waits for a person: sends held for approval, and person-only actions agents asked for.

Parameters

address string, in query
One address.
all string, in query
true includes those already decided.

Answers

200
Done
401
No valid key, session or token
404
Not found, or not yours to see
Fields of the 200 answer
approvals array of Approval 
curl https://address.seleya.ai/api/v1/approvals \
  -H "Authorization: Bearer $SELEYA_KEY"

Answer 200
{
  "approvals": [
    {
      "id": "7f3c9a2e-0000-4000-8000-000000000001",
      "kind": "send",
      "summary": "send a meeting invitation to sam@beta.example",
      "address": "desk@acme.seleya.email",
      "company": "Acme",
      "asked_by": "The app Example agent",
      "status": "pending",
      "decided_at": null,
      "created_at": "2026-10-22T12:00:00Z",
      "request": {
        "to": [
          "sam@beta.example"
        ],
        "cc": [],
        "subject": "Meeting",
        "text": "Can we meet on Tuesday?",
        "transport": "auto"
      }
    }
  ]
}

An ask from its emailed link

POST /v1/approvals/by-link

Called by address.seleya.ai, signed in.

What an emailed link asks, as the confirm page shows it.

Body

token string required
The token from the emailed link's fragment.

Answers

200
Done
404
Not found, or not yours to see
Fields of the 200 answer
id string
kind send | release | allow_sender | unblock_sender | screening | approvals_mode | set_holder | retire | add_admin | remove_admin | add_contacts | hard_stop_off
summary string, or null
address string, or null
company string, or null
asked_by string
status pending | sending | approving | approved | rejected | failed | prepared
decided_at string, or null
created_at string
request object

Decide from the link

POST /v1/approvals/by-link/decide

Called by address.seleya.ai, signed in.

The confirm page's button. Opening the link decides nothing.

Body

token string required
The token from the emailed link's fragment.
decision approve | reject required
approve carries it out; reject drops it.

Answers

200
Done
403
Not allowed for this caller
404
Not found, or not yours to see
409
Conflicts with the current state
422
A value is refused; the message says which

One ask

GET /v1/approvals/{id}

Called with a key or a person signed in.

One ask, with what was asked and where it stands.

Parameters

id string, in path required
Its id.

Answers

200
Done
401
No valid key, session or token
404
Not found, or not yours to see
Fields of the 200 answer
id string
kind send | release | allow_sender | unblock_sender | screening | approvals_mode | set_holder | retire | add_admin | remove_admin | add_contacts | hard_stop_off
summary string, or null
address string, or null
company string, or null
asked_by string
status pending | sending | approving | approved | rejected | failed | prepared
decided_at string, or null
created_at string
request object 
curl https://address.seleya.ai/api/v1/approvals/ID \
  -H "Authorization: Bearer $SELEYA_KEY"

Answer 200
{
  "id": "7f3c9a2e-0000-4000-8000-000000000001",
  "kind": "send",
  "summary": "send a meeting invitation to sam@beta.example",
  "address": "desk@acme.seleya.email",
  "company": "Acme",
  "asked_by": "The app Example agent",
  "status": "pending",
  "decided_at": null,
  "created_at": "2026-10-22T12:00:00Z",
  "request": {
    "to": [
      "sam@beta.example"
    ],
    "cc": [],
    "subject": "Meeting",
    "text": "Can we meet on Tuesday?",
    "transport": "auto"
  }
}

Approve

POST /v1/approvals/{id}/approve

Called by address.seleya.ai, signed in.

Approves and carries it out. A person only.

Parameters

id string, in path required
Its id.

Answers

200
Done
401
No valid key, session or token
403
Not allowed for this caller
404
Not found, or not yours to see
409
Conflicts with the current state

Reject

POST /v1/approvals/{id}/reject

Called by address.seleya.ai, signed in.

Refuses it; nothing is done. A person only.

Parameters

id string, in path required
Its id.

Answers

200
Done
401
No valid key, session or token
403
Not allowed for this caller
404
Not found, or not yours to see
409
Conflicts with the current state
Fields of the 200 answer
id string
kind send | release | allow_sender | unblock_sender | screening | approvals_mode | set_holder | retire | add_admin | remove_admin | add_contacts | hard_stop_off
summary string, or null
address string, or null
company string, or null
asked_by string
status pending | sending | approving | approved | rejected | failed | prepared
decided_at string, or null
created_at string
request object

Docs