Discover the contract#
curl -fsS https://backend.honeycomb.teamofsilicons.com/api/contracts
curl -fsS https://backend.honeycomb.teamofsilicons.com/api/v1/iam \
-H 'Honeycomb-API-Version: v1' \
-H 'Honeycomb-Client-Version: 0.1.0'
/api/contracts remains available when a version retires. The API path selects the major contract. An explicit version header must match it. See Compatibility for lifecycle rules.
Headers#
| Header | Use |
|---|---|
Authorization: Bearer … |
Honeycomb user session for authenticated operations. |
Honeycomb-API-Version: v1 |
Explicit contract selection matching the URL. |
Honeycomb-Client-Version: 0.1.0 |
Semantic client version for minimum-version policy. |
Idempotency-Key |
Stable key for a logical mutation, 16–255 visible ASCII characters. |
If-Match |
Current integer resource revision for revision-guarded mutations. |
X-Testing-Environment-Key |
Explicit isolated environment root key when applicable. |
X-Honeycomb-Telemetry: false |
Opt out of optional diagnostics for this request. |
Do not send tokens to storage hosts or arbitrary redirect destinations. Use the official client when possible; it centralizes encoding, limits, and integrity checks.
Read a catalog page#
curl -fsS 'https://backend.honeycomb.teamofsilicons.com/api/v1/apps?q=briefcase&page=1'
Catalog pages contain items, page, per_page, and total. App records include app_id, org_id, name, description, visibility, state, configuration/IAM revisions, requested/effective config, latest release version, and aggregate community counts. Treat unknown response fields as compatible extensions.
Use percent-encoded path segments for application IDs: my-org%3Emy-app. An authenticated request can include accessible private results; anonymous results remain public.
Creation and uploads#
POST /api/v1/apps accepts the AppInput JSON. Updates use PUT /api/v1/apps/{id} with a complete input and If-Match.
POST /api/v1/apps/{id}/releases accepts raw gzip archive bytes with Content-Type: application/gzip, not a multipart form. Include mutation headers. The maximum archive is 512 MiB. POST /api/v1/packages/validate validates the same package format.
Logo uploads use raw bytes with Content-Type: application/octet-stream at POST /api/v1/organizations/{org}/logos; limit 2 MiB. Releases and assets covers image rules and visibility.
GET /api/v1/apps/{id}/download?version=1.0.0 downloads an authorized release. Verify its byte length and SHA-256 against the release record, then validate the archive before extracting it.
Errors and pending results#
Errors use an error object with code, message, and optional details. Failed CLI commands exit nonzero; a raw HTTP client must check the response status. Authentication failures require a fresh valid grant, revision conflicts require reading current state, and integration failures require repairing the named dependency.
Cross-service mutations may return durable pending work. Inspect its operation ID rather than assuming the change is active. Exact bodies and types are defined in the core models and client methods.
Registered routes#
The following index is generated from the server router. It lists implemented routes, not a claim that every dependent production integration is complete. Authentication and role checks still apply to each handler.
| Method | Path | Handler |
|---|---|---|
GET |
/health |
health |
GET |
/api/contracts |
discovery |
GET |
/api/v1/contract |
discovery |
GET |
/api/v1/iam |
iam |
POST |
/api/v1/auth/login |
login |
POST |
/api/v1/auth/refresh |
refresh |
POST |
/api/v1/auth/logout |
logout |
GET |
/api/v1/auth/status |
status |
POST |
/api/v1/reports |
report |
POST |
/api/v1/telemetry |
ingest |
GET |
/api/v1/review-requests |
inbox |
POST |
/api/v1/review-requests/{id}/activate |
activate |
GET |
/api/v1/review-requests/{id}/{provider} |
detail |
POST |
/api/v1/review-requests/{id}/{provider}/messages |
message |
POST |
/api/v1/review-requests/{id}/plan |
retry_plan |
POST |
/api/v1/review-requests/{id}/{provider}/decisions |
decide |
GET |
/api/v1/organizations/{org}/scope-catalog |
scopes |
GET |
/api/v1/apps |
search |
POST |
/api/v1/apps |
create_app |
POST |
/api/v1/organizations/{org}/logos |
upload |
GET |
/api/v1/apps/{id} |
get_app |
PUT |
/api/v1/apps/{id} |
update_app |
GET |
/api/v1/apps/{id}/operations |
app_operations |
GET |
/api/v1/apps/{id}/webhook |
status |
POST |
/api/v1/apps/{id}/webhook |
mutate |
POST |
/api/v1/operations/{id}/webhook-retry |
retry |
GET |
/api/v1/apps/{id}/reconciliation |
status |
POST |
/api/v1/apps/{id}/reconciliation |
refresh |
GET |
/api/v1/apps/{id}/releases |
releases |
POST |
/api/v1/apps/{id}/releases |
upload_release |
GET |
/api/v1/apps/{id}/download |
download |
POST |
/api/v1/apps/{id}/secret-rotations |
rotate |
POST |
/api/v1/operations/{id}/result |
recover |
GET |
/api/v1/apps/{id}/reviews |
reviews |
PUT |
/api/v1/apps/{id}/reviews |
review |
PUT |
/api/v1/apps/{id}/star |
star |
DELETE |
/api/v1/apps/{id}/star |
unstar |
POST |
/api/v1/apps/{id}/publication |
request_publication |
GET |
/api/v1/apps/{id}/publication |
publication |
POST |
/api/v1/apps/{id}/publication/messages |
message |
GET |
/api/v1/operations/{id} |
operation |
POST |
/api/v1/operations/{id}/retry |
retry_operation |
POST |
/api/v1/packages/validate |
validate_archive |
GET |
/api/v1/organizations/{org}/drafts |
drafts |
PUT |
/api/v1/organizations/{org}/drafts/{id} |
save_draft |
GET |
/api/v1/environments |
environments |
POST |
/api/v1/environments |
create_environment |
GET |
/api/v1/environments/{id} |
environment |
POST |
/api/v1/environments/{id}/key |
environment_key |
POST |
/api/v1/environments/{id}/actions/{action} |
environment_action |
POST |
/api/v1/environments/{id}/imports |
import |
GET |
/api/v1/environments/{id}/retention |
status |
PUT |
/api/v1/environments/{id}/retention |
update |
POST |
/api/v1/environments/{id}/apps/{app}/activity |
report |
POST |
/webhook/ |
webhook |