ForjioHuudisIdentityPlugipayPaymentsStorlaunchE-commerceFulkrumaFulfillmentRiplloMarketingDeplloThis product
Depllo Docs
⌘K

API reference

The Depllo REST API. Every route below is mounted under /api/v1 and rides the family { data, error, meta } envelope.

Base URL

https://depllo.forjio.com/api/v1

Authentication

Portal API routes accept a Bearer access token issued by Huudis:

Authorization: Bearer <access-token>

The easiest way to get a token is the CLI — depllo auth login stores a session, and the CLI attaches the token for you. All calls are scoped to your active workspace (Huudis account). Browser sessions authenticate by cookie instead; the runner protocol uses a separate runner token.

Response envelope

{
  "data": { },
  "error": null,
  "meta": { "requestId": "req_...", "timestamp": "2026-01-01T00:00:00Z" }
}

On error, data is null and error carries an UPPER_SNAKE_CASE code (NOT_FOUND, VALIDATION_ERROR, CONFLICT, AUTH_REQUIRED, FORBIDDEN, PIPELINE_NOT_CREATED, UPSTREAM_ERROR, …) plus a human-readable message.

Idempotency

Mutating requests accept an Idempotency-Key header. Re-sending the same key returns the original result instead of creating a duplicate.

Pagination

List endpoints that paginate use an opaque cursor query param and return meta.cursor (the next cursor) and meta.hasMore.

Projects

List projects

GET /projects — every project in your workspace, each with its latest pipeline for the dashboard chip.

Create a project

POST /projects

{
  "repoFullName": "your-org/your-repo",
  "name": "your-repo",
  "defaultBranch": "main",
  "configPath": ".depllo-ci.yml",
  "cloneToken": "ghp_… (optional, for private repos)"
}

Creating a project also registers the GitHub webhook. The response includes a webhook field indicating whether that succeeded.

Get / delete a project

  • GET /projects/:id
  • DELETE /projects/:id — removes the project and all its pipelines, jobs, variables, and schedules.

Re-create the webhook

POST /projects/:id/webhook — idempotent; the settings-page "re-create" action.

Pipelines

List a project's pipelines

GET /projects/:id/pipelines?cursor=<cursor> — newest first, cursor-paginated.

Run a pipeline manually

POST /projects/:id/pipelines

{ "ref": "main", "variables": { "DEPLOY_ENV": "staging" } }

Depllo fetches .depllo-ci.yml at the ref and creates the pipeline. Returns 422 PIPELINE_NOT_CREATED if workflow: rules excludes it.

Get a pipeline (with jobs)

GET /projects/:id/pipelines/:iid — by the display iid (42). Returns the pipeline plus its jobs and stage order (the DAG page shape). The same detail is available by id at GET /pipelines/:id.

Cancel / retry

  • POST /projects/:id/pipelines/:iid/cancel (or POST /pipelines/:id/cancel)
  • POST /projects/:id/pipelines/:iid/retry (or POST /pipelines/:id/retry)

Jobs

Get a job (with artifacts)

GET /jobs/:id

Job actions

  • POST /jobs/:id/retry
  • POST /jobs/:id/play — start a manual job.
  • POST /jobs/:id/cancel

Logs

  • GET /jobs/:id/log?from=<seq> — paged log chunks from a sequence number; the response includes complete and lastSeq.
  • GET /jobs/:id/log/stream?from=<seq> — SSE tail. Emits chunk events, : ping heartbeats, and a final done event with the terminal status.

Artifact download

GET /jobs/:id/artifacts/:artId/download — streams the .tar.gz.

Variables

  • GET /projects/:id/variables — values are never returned in full, only a last-4 preview.
  • POST /projects/:id/variables
{ "key": "NPM_TOKEN", "value": "…", "masked": true, "protected": false, "fileType": false }
  • PATCH /projects/:id/variables/:varId
  • DELETE /projects/:id/variables/:varId

Schedules

  • GET /projects/:id/schedules
  • POST /projects/:id/schedules
{ "cron": "0 3 * * *", "ref": "main", "active": true, "variables": { "NIGHTLY": "1" } }
  • PATCH /projects/:id/schedules/:schedId
  • DELETE /projects/:id/schedules/:schedId
  • GET /schedules — all schedules across your workspace.

Cron is a 5-field expression evaluated in WIB (Asia/Jakarta).

Runners

  • GET /runners — shared plus workspace runners.
  • POST /runners/:id/pause
  • POST /runners/:id/resume

Usage

GET /usage — compute minutes used this calendar month for your workspace, plus the tier limit:

{
  "accountId": "acc_…",
  "periodStart": "2026-07-01T00:00:00.000Z",
  "minutesUsed": 128,
  "tier": "growth",
  "minutesLimit": 6000,
  "softWarn": false,
  "exhausted": false
}

Public

Status badge

GET /public/badges/:badgeToken/pipeline.svg — no auth; the latest default-branch pipeline status as an SVG. See Status badges.

GitHub webhook intake

POST /webhooks/github/:projectId — called by GitHub, not you. HMAC-verified with the per-project secret. push and pull_request events create pipelines.