API Reference

    The ByteOr Cloud API is a JSON REST API. All authenticated endpoints require either a Bearer token (user/org-scoped), an enrollment token (one-time agent registration), or an agent key (per-agent long-lived credential).

    Base URLs for hosted environments are listed in Resource Hierarchy → Hosted Environments.

    Machine-readable index

    Health & Observability

    Unauthenticated endpoints used by load balancers and monitoring stacks.

    MethodPathAuthDescription
    GET/readyznoneReturns 200 when the service is ready to accept traffic.
    GET/healthznoneReturns 200 when the service is alive. Used for liveness probes.
    GET/metricsnonePrometheus-format metrics scrape endpoint.

    Auth

    OAuth 2.0 login flow. The API issues a Bearer token on successful callback.

    MethodPathAuthDescription
    GET/auth/loginnoneInitiates the OAuth login flow; redirects to the identity provider.
    GET/auth/callbacknoneOAuth callback. Exchanges the authorization code for a session token.

    Organizations

    Top-level tenant resource. Every project, environment, and agent belongs to exactly one organization.

    MethodPathAuthDescription
    GET/api/v1/orgsbearerList organizations the caller has access to.
    POST/api/v1/orgsbearerCreate a new organization.
    GET/api/v1/orgs/{org_id}bearerRetrieve a single organization by ID.
    PUT/api/v1/orgs/{org_id}bearerUpdate organization metadata (name, settings).

    Projects

    A project groups related environments, pipeline drafts, and deployments under one organization.

    MethodPathAuthDescription
    GET/api/v1/orgs/{org_id}/projectsbearerList all projects in the organization.
    POST/api/v1/orgs/{org_id}/projectsbearerCreate a new project.
    GET/api/v1/orgs/{org_id}/projects/{project_id}bearerRetrieve a project by ID.
    PUT/api/v1/orgs/{org_id}/projects/{project_id}bearerUpdate project metadata.
    DELETE/api/v1/orgs/{org_id}/projects/{project_id}bearerDelete a project and all nested resources.

    Environments

    An environment represents a deployment target (e.g., production, staging). Agents and deployments are scoped to an environment.

    MethodPathAuthDescription
    GET.../projects/{project_id}/environmentsbearerList environments in a project.
    POST.../projects/{project_id}/environmentsbearerCreate a new environment.
    GET.../environments/{env_id}bearerRetrieve an environment by ID.
    PUT.../environments/{env_id}bearerUpdate environment settings.
    DELETE.../environments/{env_id}bearerDelete an environment.

    Pipeline Drafts & Versions

    Drafts are mutable pipeline definitions. Promoting a draft creates an immutable version that can be deployed.

    MethodPathAuthDescription
    GET.../environments/{env_id}/draftsbearerList pipeline drafts in an environment.
    POST.../environments/{env_id}/draftsbearerCreate a new pipeline draft.
    PUT.../drafts/{id}bearerUpdate a draft's spec or metadata.
    POST.../drafts/{id}/previewbearerDry-run validation. Returns compiled output without persisting a version.
    POST.../drafts/{id}/versionbearerPromote the draft to an immutable pipeline version.
    GET.../environments/{env_id}/versionsbearerList all pipeline versions in an environment.

    Config Bundles

    Bundles package a pipeline version together with runtime configuration for deployment to agents.

    MethodPathAuthDescription
    GET.../environments/{env_id}/config-bundlesbearerList config bundles.
    POST.../environments/{env_id}/config-bundlesbearerCreate a config bundle from a pipeline version.
    GET.../config-bundles/{id}bearerRetrieve a config bundle by ID.

    Agents

    Agents are registered via enrollment tokens and then authenticated with long-lived agent keys.

    MethodPathAuthDescription
    POST.../environments/{env_id}/agentsenrollment tokenEnroll a new agent. Returns an agent ID and API key.
    GET.../environments/{env_id}/agentsbearerList agents in an environment.
    GET/api/v1/agents/{id}agent keyRetrieve the agent's own record.
    POST/api/v1/agents/{id}/heartbeatagent keySend a heartbeat with status and resource usage.
    POST/api/v1/agents/{id}/artifactsagent keyUpload runtime artifacts (incident captures, telemetry).
    POST/api/v1/agents/{id}/deploymentagent keyReport deployment status back to the control plane.
    GET/api/v1/agents/{id}/signing-keyagent keyRetrieve the current artifact signing key.

    Deployments

    Deployments push a config bundle to one or more agents. They follow an approval-gated lifecycle.

    MethodPathAuthDescription
    GET.../environments/{env_id}/deploymentsbearerList deployments in an environment.
    POST.../environments/{env_id}/deploymentsbearerCreate a deployment request. Enters pending_approval if approvals are enabled.
    GET.../deployments/{id}bearerRetrieve deployment details and status.
    POST.../deployments/{id}/rollbackbearerInitiate a rollback to the previously active deployment.

    Artifacts & Replay

    Artifacts are immutable records produced by agents (incident captures, telemetry snapshots). Replay re-executes an artifact through the original pipeline version.

    MethodPathAuthDescription
    GET.../environments/{env_id}/artifactsbearerList artifacts in an environment.
    GET.../artifacts/{id}bearerRetrieve a single artifact by ID.
    POST.../artifacts/{id}/replaybearerSubmit the artifact for deterministic replay.

    Approvals

    Approval gates enforce human review before deployments proceed.

    MethodPathAuthDescription
    GET.../environments/{env_id}/approvalsbearerList approvals for an environment.
    POST.../environments/{env_id}/approvalsbearerCreate an approval decision (approve or deny).
    GET.../approvals/{id}bearerRetrieve an approval record by ID.
    Provenance
    Need the canonical source?
    Use the public hub to orient yourself, then jump to repo-owned docs or rustdoc when you need contract-level detail.
    Source-of-truth modelRepo docs index