APIs and automation

Autodisc's API is a control-plane API. It operates on projects, environments, repositories, Change Requests, artifacts, deployments, and webhooks, including project-scoped Servers. It does not expose Dokploy, HostVDS, container, or database-provider credentials to customer workflows.

The base path for the versioned endpoints on this page is:

https://api.autodisc.xyz/api/v1

Use the dashboard or CLI for browser-user operations unless an endpoint is documented as a customer integration. Internal connector routes and private runtime-provider APIs are not customer APIs.

Resource model

Display names and provider IDs are not interchangeable. API paths use Autodisc UUIDs unless a field explicitly says it contains a GitHub provider ID.

Authentication

There are three different credential classes:

• A browser or CLI session represents a person and is evaluated through account and project permissions.
• A GitHub Actions OIDC token is exchanged for a short-lived CI session scoped to one repository, commit, project, environment, and capability set.
• A managed connector key is for Autodisc-operated services. It is not a customer API key and should not be copied into a repository.

GitHub.com workflows should use OIDC. Do not store a permanent Autodisc token as a GitHub secret for this flow.

For server-side customer automation, create a scoped API key under Account → Tokens and send it as X-API-Key. Never embed an API key in browser code.

TypeScript SDK

Install the public SDK:

npm install @autodisc/sdk

The SDK is developed in the public AutoDisc/autodisc-js repository.

Provisioning is quote-first and asynchronous:

import { Autodisc } from "@autodisc/sdk";

const autodisc = new Autodisc({
  apiKey: process.env.AUTODISC_API_KEY!,
});

const projectId = process.env.AUTODISC_PROJECT_ID!;
const quote = await autodisc.servers.quote(projectId, {
  region: "eu-west2",
  shape_code: "micro-1",
  storage_gb: 10,
  public_ipv4_enabled: true,
  quota_behavior: "stop",
});

const created = await autodisc.servers.create(projectId, {
  name: "preview-482",
  quote_token: quote.token,
  idempotency_key: "preview-482",
});

const server = await autodisc.servers.wait(projectId, created.server.id);

Use a stable idempotency key for retries. A successful create returns 202 and a lifecycle operation; it does not mean the Server is ready yet.

The REST collection is:

GET  /projects/{project_id}/servers
POST /projects/{project_id}/servers/quotes
POST /projects/{project_id}/servers
GET  /projects/{project_id}/servers/{server_id}
POST /projects/{project_id}/servers/{server_id}/lifecycle

Bind a GitHub workflow

An authorized project member can create the repository-to-environment policy with the CLI:

autodisc github-actions bind \
  --project PROJECT_UUID \
  --environment ENVIRONMENT_UUID \
  --repository REPOSITORY_UUID \
  --mode actions_managed \
  --workflow 'acme/api/.github/workflows/autodisc.yml@refs/heads/main' \
  --ref 'refs/heads/main' \
  --event push workflow_dispatch \
  --github-environment production

--repository is the canonical Autodisc repository UUID, not GitHub's numeric repository ID. Use an exact workflow and ref allowlist for production.

The equivalent endpoint is:

PUT /projects/{project_id}/repository-deployment-binding

It accepts:

{
  "environment_id": "ENVIRONMENT_UUID",
  "repository_id": "REPOSITORY_UUID",
  "trigger_mode": "actions_managed",
  "allowed_workflow_refs": [
    "acme/api/.github/workflows/autodisc.yml@refs/heads/main"
  ],
  "allowed_refs": ["refs/heads/main"],
  "allowed_events": ["push", "workflow_dispatch"],
  "github_environment_name": "production",
  "enabled": true
}

Only one trigger owner should be enabled for a repository binding: actions_managed or autodisc_managed. This prevents a push from creating two independent deployment requests.

Exchange GitHub OIDC

The workflow needs:

permissions:
  contents: read
  id-token: write

Request a GitHub identity token with the Autodisc audience, then exchange it:

OIDC_RESPONSE="$(
  curl --fail-with-body \
    -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
    "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=autodisc"
)"

OIDC_TOKEN="$(jq -r .value <<<"$OIDC_RESPONSE")"

SESSION_RESPONSE="$(
  curl --fail-with-body \
    -H "Content-Type: application/json" \
    -d "$(jq -n \
      --arg token "$OIDC_TOKEN" \
      --arg project "$AUTODISC_PROJECT_ID" \
      --arg environment "$AUTODISC_ENVIRONMENT_ID" \
      '{
        id_token: $token,
        project_id: $project,
        environment_id: $environment,
        capabilities: ["artifact:write"]
      }')" \
    https://api.autodisc.xyz/api/v1/ci/github/session
)"

AUTODISC_CI_TOKEN="$(jq -r .access_token <<<"$SESSION_RESPONSE")"
echo "::add-mask::$AUTODISC_CI_TOKEN"

Autodisc verifies the repository, commit SHA, ref, workflow reference, event, GitHub environment, and binding. The returned adci_… bearer token expires quickly and cannot be reused for another repository or commit.

Never print the GitHub identity token or CI token to job output.

Register immutable artifacts

The currently implemented CI API registers artifacts for the published Change Request revision matching the workflow commit:

POST /ci/github/change-request/artifacts

Example:

curl --fail-with-body \
  -H "Authorization: Bearer $AUTODISC_CI_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n \
    --arg sha "$GITHUB_SHA" \
    --arg image "$IMAGE_WITH_DIGEST" \
    '{
      manifest: {
        schema: "autodisc.artifact-manifest/v1",
        commit_sha: $sha,
        source_ref: env.GITHUB_REF,
        services: [
          {
            service_key: "api",
            image: $image
          }
        ]
      }
    }')" \
  https://api.autodisc.xyz/api/v1/ci/github/change-request/artifacts

IMAGE_WITH_DIGEST must look like:

registry.example.com/acme/api@sha256:0123456789abcdef…64-hex-characters-total

Mutable tags such as :latest are not release identities. The manifest commit must match the OIDC session, service keys must be unique, and the endpoint normalizes and hashes the manifest before registration.

Current GitHub Actions boundary

The public GitHub CI implementation on this branch currently supports:

• repository/environment binding;
• GitHub OIDC exchange;
• short-lived scoped CI sessions; and
• artifact registration for a published Change Request revision.

It does not yet expose a customer endpoint that creates a canonical deployment and follows its rollout event stream. A successful artifact registration means “this revision has verified build inputs,” not “the application is deployed.”

Until the deployment API is implemented, use the project workspace to approve and apply the exact Change Request, then verify build, rollout, health, and application behavior there. Do not make a GitHub job green merely because artifact registration returned 201.

Project webhooks

Project webhooks currently support:

• deployment.succeeded
• deployment.failed

Create them in Project Settings → Webhooks. The API collection is:

GET    /projects/{project_id}/webhooks/events
GET    /projects/{project_id}/webhooks
POST   /projects/{project_id}/webhooks
PATCH  /projects/{project_id}/webhooks/{webhook_id}
DELETE /projects/{project_id}/webhooks/{webhook_id}
POST   /projects/{project_id}/webhooks/{webhook_id}/rotate-secret
GET    /projects/{project_id}/webhooks/{webhook_id}/deliveries
POST   /projects/{project_id}/webhooks/{webhook_id}/deliveries/{delivery_id}/retry

A delivered body has this shape:

{
  "id": "EVENT_UUID",
  "type": "deployment.succeeded",
  "created_at": "2026-07-25T20:00:00Z",
  "project_id": "PROJECT_UUID",
  "data": {}
}

Important headers:

X-Autodisc-Event
X-Autodisc-Delivery
X-Autodisc-Timestamp
X-Autodisc-Signature-256

Verify the signature over:

TIMESTAMP + "." + RAW_REQUEST_BODY

using HMAC-SHA256 and the webhook secret. Compare the expected and received signatures in constant time, reject stale timestamps, and deduplicate on X-Autodisc-Delivery.

Node example:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyAutodiscWebhook(
  rawBody: Buffer,
  timestamp: string,
  received: string,
  secret: string,
): boolean {
  const expected = `sha256=${createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest("hex")}`;

  const left = Buffer.from(expected);
  const right = Buffer.from(received);
  return left.length === right.length && timingSafeEqual(left, right);
}

Return a 2xx response quickly and process slow work asynchronously. Deliveries may be duplicated or arrive after a retry.

Idempotency and automation rules

• Treat a repository, commit, environment, and manifest as immutable inputs.
• Reuse the platform's canonical IDs; do not persist private provider IDs.
• Make webhook receivers idempotent.
• Do not infer deployment success from source upload or artifact registration.
• Do not expose CI tokens, OIDC tokens, database URLs, or authorization headers in logs.
• Require a real health and behavior check before promotion.
• Keep production approval separate from repository write access.