HTTP API

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#

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.

Release uploads accept 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 format-1 package, which retains semantic-version compatibility for historical archives.

Release records include visibility, configuration_revision, permission_approval_required, and optional approval_status. For public apps, normal lists, downloads (including a requested version), and latest_version select only public releases. Managers can use the v2 list's include_private=true query to inspect pending releases; this does not grant install or update access to those releases. An upload receipt includes the stored release's status in its release object. Approval of the matching configuration publishes the release automatically after archive reconciliation.

The CLI, Rust client and console use v2 for release operations. Authentication, app configuration, catalog, publication and testing-environment APIs remain v1. There is no automatic major-version fallback. Existing immutable releases remain readable with their original versions and bytes.

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/v2/apps/{id}/download?channel=prod&version=1.0.0 downloads an authorized production 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.