HTTP API

These pages describe ShellOrbit as it runs today. Breaking changes to the HTTP API are announced before they ship, and existing request and response shapes stay supported.

How do I authenticate?

Bearer token. Create a key in the dashboard, store it as a secret, and send it on every request.

curl https://api.shellorbit.com/v1/endpoints \
  -H "authorization: Bearer $SHELLORBIT_API_KEY"

Keys carry a scope, either read or read and write, and can be revoked individually. A revoked key stops working immediately.

What are the main resources?

Method and path	What it does
`GET /v1/endpoints`	List endpoints
`POST /v1/endpoints`	Create an endpoint
`GET /v1/endpoints/{id}`	Read one endpoint with its configuration
`PATCH /v1/endpoints/{id}`	Update destinations, retry policy, or alerts
`DELETE /v1/endpoints/{id}`	Delete an endpoint and stop new receipts
`GET /v1/events`	List events, filtered by endpoint, status, type, or time
`GET /v1/events/{id}`	Read one event with headers, body, and attempts
`POST /v1/events/{id}/replay`	Replay one event
`POST /v1/replays`	Replay a filtered set
`GET /v1/usage`	Current period volume and projected overage

How is a list paginated?

Cursor based. A response carries next_cursor when more rows exist.

{
  "data": [ { "id": "evt_9c41f0", "status": "delivered", "attempts": 3 } ],
  "next_cursor": "ZXZ0Xzk1MmEx"
}

Pass it back as cursor to continue. Cursors are stable across inserts, so paging through a busy endpoint does not skip or repeat rows.

What do errors look like?

{
  "error": {
    "type": "invalid_request",
    "message": "destination_url must use https",
    "param": "destination_url"
  }
}

Status codes follow the usual meanings: 400 for a bad request, 401 for a missing or revoked key, 403 for a scope problem, 404 for an unknown id, 429 when rate limited, and 5xx for our failures. Retry 429 and 5xx with backoff.

Is there a CLI?

Not yet. Everything below is a plain HTTP API, so a few lines of curl or your language’s HTTP client does the same job, and that is what the examples show. If a CLI would genuinely save you time, say so at support@shellorbit.com: it is worth building when somebody actually wants it and not before.