AllternitBus API - Allternit Docs

Overview

The AllternitBus API provides the runtime surface agents use to send and receive messages, store encrypted secrets, resolve connector credentials, and manage identity channels such as email, phone, and wallet addresses. All authenticated routes are mounted under /api/v1 and require a valid bearer token via the platform auth middleware. The public inbound webhook is mounted at /webhooks/photon and is called server-to-server by Photon.codes.

Base URL

Authenticated surface:

https://api.allternit.com/api/v1

Public webhook surface:

https://api.allternit.com/webhooks/photon

For local development:

http://127.0.0.1:8013/api/v1
http://127.0.0.1:8013/webhooks/photon

Authentication

All authenticated routes require a valid bearer token in the Authorization header. The inbound Photon webhook is authenticated server-to-server by Photon.codes and does not carry a Clerk session. See Authentication for details.

Endpoints

Method	Path	Description
`POST`	`/api/v1/photon/agents/:agent_id/inbox`	Deliver a message to an agent inbox.
`GET`	`/api/v1/photon/agents/:agent_id/inbox`	List messages in an agent inbox.
`PUT`	`/api/v1/agents/:agent_id/secrets/:key`	Set or update an encrypted agent secret.
`POST`	`/api/v1/agents/:agent_id/secrets/resolve`	Resolve one or more agent secrets by reference.
`POST`	`/api/v1/agents/:agent_id/connectors/resolve`	Resolve connector credentials for an agent.
`GET`	`/api/v1/agents/:agent_id/identity`	Get an agent’s identity channels.
`POST`	`/api/v1/agents/:agent_id/identity/email`	Provision an email address for an agent.
`POST`	`/api/v1/agents/:agent_id/identity/phone`	Provision a phone number for an agent.
`POST`	`/api/v1/photon/sessions/:session_id/bridge`	Bridge a session to another surface.
`POST`	`/webhooks/photon`	Public webhook for inbound Photon messages.

Message inbox

Send a message

POST /api/v1/photon/agents/:agent_id/inbox

Delivers a message to the agent’s inbox. The route path is kept for backward compatibility with the Photon.codes integration.

Request body

Field	Type	Required	Description
`from`	string	Yes	Sender identifier.
`content`	string	Yes	Message body.
`surface`	string	No	Surface or channel the message arrived on.

Example request

curl -X POST https://api.allternit.com/api/v1/photon/agents/agent_018f3a7c.../inbox \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "user_2d9e...",
    "content": "Please summarize the latest report.",
    "surface": "chat"
  }'

Example response

{
  "id": "msg_7a1b...",
  "status": "delivered"
}

List inbox messages

GET /api/v1/photon/agents/:agent_id/inbox

Returns messages for the agent, newest first.

Query parameters

Parameter	Type	Description
`since`	string	ISO 8601 timestamp; only return messages created after this time.
`limit`	integer	Maximum number of messages (default `100`, max `500`).

Example request

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.allternit.com/api/v1/photon/agents/agent_018f3a7c.../inbox?limit=10"

Example response

{
  "agent_id": "agent_018f3a7c...",
  "messages": [
    {
      "id": "msg_7a1b...",
      "from": "user_2d9e...",
      "to": "agent_018f3a7c...",
      "content": "Please summarize the latest report.",
      "surface": "chat",
      "created_at": "2026-08-13T14:22:00Z"
    }
  ]
}

Inbound webhook

Receive an inbound message

POST /webhooks/photon

Public webhook called by Photon.codes when an inbound SMS or message arrives. The payload is routed to the agent whose identity channel matches the to phone number. No bearer token is required.

Request body

Field	Type	Required	Description
`from`	string	Yes	Originating address.
`to`	string	Yes	Destination phone number.
`body`	string	Yes	Message body.
`channel`	string	Yes	Channel the message arrived on.
`message_id`	string	Yes	External message identifier.

Example request

curl -X POST https://api.allternit.com/webhooks/photon \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "body": "Hello, can you help me?",
    "channel": "sms",
    "message_id": "photon_msg_9c1d..."
  }'

Example response

{
  "status": "accepted"
}

Secrets

Set a secret

PUT /api/v1/agents/:agent_id/secrets/:key

Stores an encrypted secret value for the agent. Values are sealed at rest via token_crypto. If a secret with the same key already exists, it is overwritten.

Request body

Field	Type	Required	Description
`value`	string	Yes	Secret value to encrypt and store.
`name`	string	No	Human-readable name; defaults to `:key`.
`description`	string	No	Optional description.
`required`	boolean	No	Whether the secret is required for agent operation.

Example request

curl -X PUT https://api.allternit.com/api/v1/agents/agent_018f3a7c.../secrets/PHOTON_API_KEY \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "sk_live_...",
    "name": "Photon API Key",
    "description": "Project secret for outbound messaging.",
    "required": true
  }'

Example response

204 No Content

Resolve secrets

POST /api/v1/agents/:agent_id/secrets/resolve

Decrypts and returns values for the requested secret references. Required secrets that are missing or cannot be decrypted are reported in missing and errors.

Request body

Field	Type	Required	Description
`refs`	array	Yes	List of secret references to resolve.

Each reference:

Field	Type	Required	Description
`name`	string	Yes	Human-readable name.
`key`	string	Yes	Stored secret key.
`required`	boolean	No	Whether absence is reported as missing.

Example request

curl -X POST https://api.allternit.com/api/v1/agents/agent_018f3a7c.../secrets/resolve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "refs": [
      { "name": "Photon API Key", "key": "PHOTON_API_KEY", "required": true }
    ]
  }'

Example response

{
  "secrets": [
    {
      "key": "PHOTON_API_KEY",
      "value": "sk_live_...",
      "source": "vault"
    }
  ],
  "missing": [],
  "errors": []
}

Connectors

Resolve connector credentials

POST /api/v1/agents/:agent_id/connectors/resolve

Resolves live credentials for the requested connector bindings. The route first looks up a connected connector_connections row for the caller, then falls back to legacy allternit_vault_credentials that belong to the agent and user.

Request body

Field	Type	Required	Description
`bindings`	array	Yes	Connector bindings to resolve.

Each binding:

Field	Type	Required	Description
`connector_id`	string	Yes	Connector identifier.
`provider`	string	Yes	Provider slug.
`label`	string	No	Display label used in missing-credential messages.
`capabilities`	array	No	Capability strings.
`autonomous`	boolean	No	Whether the connector may act autonomously.
`allowed_actions`	array	No	Action allow-list.

Example request

curl -X POST https://api.allternit.com/api/v1/agents/agent_018f3a7c.../connectors/resolve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bindings": [
      {
        "connector_id": "conn_4d5e...",
        "provider": "photon",
        "label": "Photon SMS",
        "required": true
      }
    ]
  }'

Example response

{
  "credentials": [
    {
      "connector_id": "conn_4d5e...",
      "provider": "photon",
      "key": "PHOTON_ACCESS_TOKEN",
      "value": "sk_live_...",
      "source": "connector_connections"
    }
  ],
  "missing": [],
  "errors": []
}

Identity channels

Get identity channels

GET /api/v1/agents/:agent_id/identity

Returns the agent’s bound identity channels: email, phone, and wallet. Channels that have not been provisioned are returned as null.

Example request

curl -H "Authorization: Bearer $TOKEN" \
  https://api.allternit.com/api/v1/agents/agent_018f3a7c.../identity

Example response

{
  "agent_id": "agent_018f3a7c...",
  "email": {
    "address": "[email protected]",
    "provider": "custom",
    "sendEnabled": true,
    "receiveEnabled": true
  },
  "phone": {
    "number": "+15559876543",
    "provider": "vapi",
    "voiceEnabled": true,
    "smsEnabled": true
  },
  "wallet": null
}

Provision email

POST /api/v1/agents/:agent_id/identity/email

Provisions an email address for the agent using the domain configured in ALLTERNIT_BOT_EMAIL_DOMAIN. When the mailflare agent-email rail is configured (ALLTERNIT_MAILFLARE_URL + ALLTERNIT_MAILFLARE_ADMIN_KEY), this creates a real mailbox on the mailflare worker, mints a mailbox-scoped send/read API key, seals it server-side, and stores the channel with provider "mailflare". The agent can then genuinely receive and (subject to approval) send internet email. When mailflare is not configured, the endpoint falls back to minting an address record only (provider "commrails") with no send/receive transport. Provisioning is idempotent: re-provisioning an agent returns its existing channel.

Example request

curl -X POST https://api.allternit.com/api/v1/agents/agent_018f3a7c.../identity/email \
  -H "Authorization: Bearer $TOKEN"

Example response

{
  "address": "[email protected]",
  "provider": "mailflare"
}

Agent email rail

Real inbound/outbound email for agents, backed by a per-installation mailflare worker (see services/mailflare/). Inbound mail arrives as an HMAC-signed webhook and is bridged into the agent’s Rails Mail threads; outbound mail is held for human approval before it is sent.

Send email (approval-gated)

POST /api/v1/agent-email/send

Field	Type	Required	Description
`agent_id`	string	Yes	Owning agent. Must have a mailflare email channel with send enabled.
`to`	string	Yes	Recipient address.
`subject`	string	Yes	Subject line.
`text`	string	One of text/html	Plain-text body.
`html`	string	One of text/html	HTML body.

The message is not sent immediately. It is recorded as pending_approval and a review is requested on a Rails Mail thread (mail:email-out-<id>). A human approves or rejects via POST /api/rails/mail/decide with { "thread": "<thread_id>", "approve": true|false }; approving triggers the actual send and writes a receipt with the provider message id. The decide response includes an email object for email threads.

{
  "status": "pending_approval",
  "thread": "mail:email-out-9f1c...",
  "outbound_id": "9f1c..."
}

Email rail status

GET /api/v1/agent-email/status

Reports whether the mailflare rail is configured, the agent email domain, and whether the worker is reachable. Use this to diagnose installations.

Inbound webhook (server-to-server)

POST /api/v1/agent-email/inbound

Public route called by the mailflare worker, authenticated by an X-Email-Platform-Signature HMAC-SHA256 header against ALLTERNIT_MAILFLARE_WEBHOOK_SECRET. message.inbound events are stored and bridged into the receiving agent’s Rails Mail thread (mail:email-in-<agent>). Unknown recipients return 202 and are logged.

Provision phone

POST /api/v1/agents/:agent_id/identity/phone

Assigns a phone number to the agent from the comma-separated pool in ALLTERNIT_BOT_PHONE_POOL. The first number not already assigned to another agent is chosen.

Example request

curl -X POST https://api.allternit.com/api/v1/agents/agent_018f3a7c.../identity/phone \
  -H "Authorization: Bearer $TOKEN"

Example response

{
  "number": "+15559876543",
  "provider": "vapi"
}

Cross-surface bridge

Bridge a session

POST /api/v1/photon/sessions/:session_id/bridge

Requests a cross-surface bridge for a session. The route path is kept for backward compatibility. The payload is echoed back with a bridged status.

Request body

Field	Type	Required	Description
`target_surface`	string	Yes	Surface to bridge the session to.
`payload`	object	Yes	Opaque bridge payload.

Example request

curl -X POST https://api.allternit.com/api/v1/photon/sessions/sess_9c1d.../bridge \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target_surface": "cowork",
    "payload": { "thread_id": "thread_3f8a..." }
  }'

Example response

{
  "session_id": "sess_9c1d...",
  "target_surface": "cowork",
  "status": "bridged",
  "payload": { "thread_id": "thread_3f8a..." }
}

Error codes

Status	Code	Meaning
`200 OK`	—	Request succeeded.
`202 Accepted`	—	Message or bridge accepted for processing.
`204 No Content`	—	Secret stored successfully.
`400 Bad Request`	`invalid_key`	Secret key cannot be empty.
`400 Bad Request`	`empty_value`	Secret value cannot be empty.
`401 Unauthorized`	—	Missing or invalid bearer token.
`403 Forbidden`	`forbidden`	Agent does not belong to the caller.
`404 Not Found`	`not_found`	Agent not found.
`409 Conflict`	`phone_pool_exhausted`	No phone numbers left in the configured pool.
`409 Conflict`	`email_not_provisioned`	Agent has no mailflare email channel; provision one first.
`403 Forbidden`	`email_send_disabled`	Outbound email is disabled for this agent.
`500 Internal Server Error`	`internal_error`	Unexpected server error.
`501 Not Implemented`	`email_domain_not_configured`	`ALLTERNIT_BOT_EMAIL_DOMAIN` is not set.
`501 Not Implemented`	`mailflare_not_configured`	`ALLTERNIT_MAILFLARE_URL` / `ALLTERNIT_MAILFLARE_ADMIN_KEY` are not set.
`501 Not Implemented`	`phone_pool_not_configured`	`ALLTERNIT_BOT_PHONE_POOL` is not set.
`501 Not Implemented`	`phone_pool_empty`	`ALLTERNIT_BOT_PHONE_POOL` is empty.

​Overview

​Base URL

​Authentication

​Endpoints

​Message inbox

​Send a message

​Request body

​Example request

​Example response

​List inbox messages

​Query parameters

​Example request

​Example response

​Inbound webhook

​Receive an inbound message

​Request body

​Example request

​Example response

​Secrets

​Set a secret

​Request body

​Example request

​Example response

​Resolve secrets

​Request body

​Example request

​Example response

​Connectors

​Resolve connector credentials

​Request body

​Example request

​Example response

​Identity channels

​Get identity channels

​Example request

​Example response

​Provision email

​Example request

​Example response

​Agent email rail

​Send email (approval-gated)

​Email rail status

​Inbound webhook (server-to-server)

​Provision phone

​Example request

​Example response

​Cross-surface bridge

​Bridge a session

​Request body

​Example request

​Example response

​Error codes

​Related pages

Overview

Base URL

Authentication

Endpoints

Message inbox

Send a message

Request body

Example request

Example response

List inbox messages

Query parameters

Example request

Example response

Inbound webhook

Receive an inbound message

Request body

Example request

Example response

Secrets

Set a secret

Request body

Example request

Example response

Resolve secrets

Request body

Example request

Example response

Connectors

Resolve connector credentials

Request body

Example request

Example response

Identity channels

Get identity channels

Example request

Example response

Provision email

Example request

Example response

Agent email rail

Send email (approval-gated)

Email rail status

Inbound webhook (server-to-server)

Provision phone

Example request

Example response

Cross-surface bridge

Bridge a session

Request body

Example request

Example response

Error codes

Related pages