Skip to main content
The Spectrum API is the HTTP surface for managing a project’s webhooks, platforms, lines, and users. It’s the same thing the Photon dashboard and the photon CLI call under the hood — reach for it when you want to automate setup, drive changes from CI, or build your own internal tooling. If you’re sending and receiving messages at runtime, you want the spectrum-ts SDK or webhooks instead. This API is for the management plane around them.

​
Base URL

Every endpoint lives under a single host. HTTPS only — plaintext requests are rejected. 
https://spectrum.photon.codes

​
Authentication

The API uses HTTP Basic auth. The username is your projectId and the password is your projectSecret. Credentials are scoped to a single project and never expire on their own. 
curl -u "$PROJECT_ID:$PROJECT_SECRET" \
  "https://spectrum.photon.codes/projects/$PROJECT_ID/webhooks/"
Retrieve credentials with photon projects show or from the dashboard. If a secret leaks, rotate it with photon projects regenerate-secret.
Project credentials grant full management access to a project. Store them in a secrets manager, not in source control or shell history.

​
Response format

Every response is JSON wrapped in a { succeed, data } envelope. On success, data holds the resource: 
{
  "succeed": true,
  "data": {
    "id": "6a4d2e8c-7b1f-4d3a-9a8e-2c5d6f7e8a9b",
    "webhookUrl": "https://your-app.com/spectrum-webhook",
    "createdAt": "2026-05-14T19:00:00Z",
    "updatedAt": "2026-05-14T19:00:00Z"
  }
}
On error, succeed is false and the body carries an explanation: 
{
  "succeed": false,
  "message": "webhookUrl must be a valid URL"
}
List endpoints return an array under data rather than a single object. The HTTP status code is the source of truth for whether a call succeeded — branch on it first, then read data.

​
Response codes

CodeMeaning
200Request succeeded.
401Missing or invalid project credentials.
404Resource not found or already deleted.
409Conflict — for example, a resource with the same key already exists.
422Request body failed schema validation.
5xxSpectrum-side error. Safe to retry with backoff.

​
Where to next

Get project

The simplest endpoint to try first — fetch a project by id.

Get started with the SDK

Send and receive messages from your agent server with spectrum-ts.