Dengel API reference
This reference covers the hosted workspace Gateway and the project Git listener operations used by the quickstarts. Workspace access, membership, repository permissions, and feature availability still apply. Start with signup and access if your workspace is awaiting admission.
Gateway authentication and response format
Use https://api.dengel.dev/v1 and send Authorization: Bearer TOKEN with a delegated workspace token from the CLI reference. Choose the workspace before obtaining the token. Refresh it after an expiry, sign-in change, or workspace switch. A separate Cloudflare Access check, where configured, requires its own credential.
Read a run from Bash after setting the token:
printf 'Authorization: Bearer %s\n' "$DENGEL_GATEWAY_TOKEN" |
curl --silent --show-error --fail-with-body --header @- \
https://api.dengel.dev/v1/runs/BUILD_ID
Replace BUILD_ID with the panel's run ID. Send Content-Type: application/json on JSON writes. Keep tokens in an approved credential store and avoid tracing or logging authentication headers.
JSON success responses include api_version, surface, sources, and data, with optional warnings. Check the status of each source needed for your decision. ok means it was read, partial means some information is missing, unavailable means it could not be checked, and not_supported means it does not provide that capability. For example, a Receipt list can have sources.build.status: ok with sources.git.status: not_supported. A successful HTTP response with an unavailable Build source cannot establish that the Receipt list is empty.
Workspace roles are cumulative: viewer reads, reviewer can add proposal feedback, contributor can open proposals and do permitted setup, and maintainer and owner can manage work subject to the specific route and named approval rules. Roles and credentials are checked separately. The delegated CLI token can perform allowed reads and writes. Approvals, landing, and starting or verifying paid work require an authorized person signed in to the panel.
Workspace reads
All paths in this table are relative to https://api.dengel.dev/v1.
| Endpoint | Result or query |
|---|---|
GET /contract |
Gateway capability inventory and known gaps. |
GET /runs, GET /runs/{id} |
Run summaries and detail at data.runs and data.run. |
GET /runs/{id}/timeline, GET /runs/{id}/verify, GET /runs/{id}/conformance |
Activity, independent verification, and evidence for acceptance checks. |
GET /runs/{id}/events?since={seq} |
Server-sent events. On reconnect, pass the last processed event ID in Last-Event-ID or since. |
GET /approval-queue, GET /needs-you/mine, GET /needs-you/{id} |
Decisions awaiting a person, the caller's own queue, and one item. |
GET /specs/{id}, GET /specs/{id}/sources |
Spec and frozen source list. |
GET /repositories, GET /git/capabilities |
Repository connections and available hosting options. |
GET /git-projects, GET /git-projects/{id}, GET /git-projects/{id}/refs |
Managed repositories, one project, and its refs. |
GET /git-projects/{id}/tree, GET /git-projects/{id}/blob, GET /git-projects/{id}/commits |
Browse using ref. Use path for a directory or file and cursor and limit for commit pagination. |
GET /git-projects/{id}/proposals, GET /git-projects/{id}/proposals/{pid} |
Proposal list or detail with head, base, digest, quote, verdict, and any Receipt summary. |
GET /git-projects/{id}/checks, GET /git-projects/{id}/check-runs?tree={digest} |
Approved checks and external results for a specific tree. |
GET /git-projects/{id}/stacks, GET /git-projects/{id}/stacks/{stack} |
Stack list and current revision. |
GET /receipts?q={text}&limit={count}, GET /receipts/{id} |
Workspace Receipt list and exact signed record. Default list limit is 50, maximum 200. |
Workspace writes and panel actions
| Endpoint | Purpose |
|---|---|
POST /specs/preview, POST /specs, POST /specs/{id}/plan |
Preview source identity, create a spec, or propose a plan using plan_toml. |
POST /git-projects/{id}/proposals |
Open a proposal for an existing candidate ref. Contributor or higher. |
POST /git-projects/{id}/proposals/{pid}/feedback |
Record reviewer feedback with text, kind, and idempotency_key. Kinds are comment and would_change. |
GET /git-projects/{id}/access-tokens, POST /git-projects/{id}/access-tokens, DELETE /git-projects/{id}/access-tokens/{token_id} |
List, issue, or revoke project credentials. Listing returns metadata at data.tokens. Issuance shows the token value once. Issuing a checks token requires maintainer or owner. |
POST /git-projects/{id}/submit-tokens, POST /agent-apps |
Issue a project submit token or register an agent app. Maintainer or owner. For a submit token, send {} for the default expiry or set ttl_secs from 3600 to 7776000. |
POST /runs/{id}/actions/pause, POST /runs/{id}/run/cancel |
Pause a run or stop its active attempt. Include reason. |
POST /specs/{id}/plan/approve, POST /specs/{id}/quote/approve |
Approve the current plan and quote in the panel. |
POST /runs/{id}/start, POST /runs/{id}/verify, POST /runs/{id}/merge |
Start managed work, request independent verification, and land through the panel. |
POST /git-projects/{id}/proposals/{pid}/verify, POST /git-projects/{id}/proposals/{pid}/approve |
Authorize the exact quote_digest and approve the exact proposal_digest in the panel. |
POST /git-projects/{id}/stacks, POST /git-projects/{id}/stacks/{stack}/restack, POST /git-projects/{id}/stacks/{stack}/prepare |
Create with idempotency_key, restack with version, or prepare a prefix with version and through (final proposal ID). |
POST /git-projects/{id}/stacks/{stack}/land |
Land a reviewed stack prefix through the panel. |
Before creating a proposal through either the Gateway or Git listener, have an owner or maintainer approve the repository checks in the panel. A repository without approved checks returns 409 checks_not_approved. For proposal creation, send candidate_ref and idempotency_key. Include expected_head with the full candidate commit so the server can refuse a moved ref. intent is optional. To attribute an agent, use a registered agent role and optionally its session. The response is HTTP 201 with the proposal data. If the response is lost, check the project and proposal state and reuse the same key for the same request.
Example proposal body. Replace the commit with the candidate's actual head and choose a unique key for this submission.
{
"candidate_ref": "refs/heads/candidate/update-readme",
"expected_head": "0123456789abcdef0123456789abcdef01234567",
"idempotency_key": "update-readme-1",
"intent": "Correct the quickstart example"
}
Git listener credentials and endpoints
Use the HTTPS repository URL from Code, normally on git.dengel.dev. For Git commands, use the displayed username and the project token as the password through a credential helper. For the listener's HTTP operations, use the appropriate project token as a bearer. These tokens are scoped to a repository or project. Gateway routes require a separate workspace identity.
| Credential | Permissions |
|---|---|
read |
Read-only Git access, including clone and fetch. |
git |
Read and push candidate refs. This is the default access-token scope. |
checks |
Read and report external CI results. |
| Submit token | Read, publish a candidate, and open a proposal as a registered agent. Issued separately from access-token scopes. |
| Git listener endpoint | Purpose |
|---|---|
GET /{repo}.git/query/read-file?rev={commit}&path={file} |
Read a file without cloning. Supply a full commit ID for a stable read. Related queries include list-tree, log, changed-paths, and diff. |
POST /{repo}.git/checks |
With a checks token, report commit, name, and status of pending, success, or failure. The result is stored against the commit's tree. |
POST /{repo}.git/propose?project={id} |
With a submit token, open a candidate proposal for the token's project. The body uses the proposal fields above and requires a registered agent. |
A Git push or check report cannot move the protected branch or certify a proposal. The workflow and Receipts reference explains the states, refusals, and landing evidence.
