Pipelines

/api/v1 operations for pipelines. See HTTP API for authentication, the error envelope, and rate limits.

Operations

GET /api/v1/pipelines

List pipelines

Returns the organization's non-deleted pipelines, including each pipeline's current run. Run state is reconciled with the provider before reading (staleness-gated), so polling this endpoint observes runs reaching a terminal status. Responses never include usage data.

Auth: API key required.

Operation ID: listPipelines

Responses:

• 200 — The organization's pipelines.
• 401 — Authentication is missing or invalid.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan pipelines list

POST /api/v1/pipelines

Create a pipeline

Provisions a pipeline synchronously (template repo plus provider project) and responds 201 with the persisted record whether provisioning ends ready or failed; branch on the returned status. Requires an API key whose role includes developer. Pass an idempotencyKey to make retries safe: repeating a create with the same key returns the existing pipeline instead of provisioning a duplicate. Initial environment variables are applied to the provider project before the first run. Omit regionPreference to use the default region.

Auth: API key required.

Operation ID: createPipeline

Request body (application/json, required):

• name (string, required)
• regionPreference (string | null, optional)
• environmentVariables (object[], optional)
• database (object, optional)
• redis (object, optional)
• idempotencyKey (string, optional)

Responses:

• 201 — The persisted pipeline record, in ready or failed status.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 403 — The caller is not permitted to perform this action.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan pipelines create

GET /api/v1/pipelines/{pipelineId}

Get a pipeline

Returns one pipeline's record, including its current run and failure state when present. Run state is reconciled with the provider before reading (staleness-gated), so poll this endpoint after a create or redeploy to observe the run reaching a terminal status. Responses never include usage data.

Auth: API key required.

Operation ID: getPipeline

Path parameters:

• pipelineId (string, required)

Responses:

• 200 — The pipeline record.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan pipelines get

DELETE /api/v1/pipelines/{pipelineId}

Delete a pipeline

Tears down the provider project and repo, then soft-deletes the record — the same semantics as deleting from the dashboard. Requires an API key whose role includes developer. Deletion is permanent. Returns 403 resource_protected when the pipeline has deletion protection enabled; protection can only be removed from the dashboard.

Auth: API key required.

Operation ID: deletePipeline

Path parameters:

• pipelineId (string, required)

Responses:

• 200 — The pipeline was deleted.
• 401 — Authentication is missing or invalid.
• 403 — The pipeline is protected from deletion (code resource_protected). Remove protection from the dashboard before deleting via the API.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.
• 502 — Response.

CLI: khotan pipelines delete

PUT /api/v1/pipelines/{pipelineId}/tags

Set a pipeline's tags

Replaces a pipeline's tag list with the submitted list and returns the stored list. Tags are normalized to lowercase slugs, so Live is stored as live. Send an empty list to remove every tag. Requires an API key whose role is owner, admin, or developer.

Auth: API key required.

Operation ID: setPipelineTags

Path parameters:

• pipelineId (string, required)

Request body (application/json, required):

• tags (string[], required) — Full tag list; it replaces the stored list. Each tag is trimmed, lowercased, and has whitespace runs replaced with "-", and repeats are removed. After that, each tag is 1-32 lowercase letters, digits, or single hyphens, with at most 10 tags. Presets: test, live, uat, dev, demo, deprecated.

Responses:

• 200 — The stored tag list, after normalization.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 403 — The caller is not permitted to perform this action.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan pipelines tags set

POST /api/v1/pipelines/{pipelineId}/redeploy

Redeploy a pipeline

Triggers a fresh production run from the tip of the pipeline's linked branch and responds 202 with the new run's initial status (queued or running). Poll the pipeline detail endpoint to observe the run reaching a terminal status. The new run picks up the currently-applied environment variables.

Auth: API key required.

Operation ID: redeployPipeline

Path parameters:

• pipelineId (string, required)

Responses:

• 202 — The new run's initial status.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 409 — Response.
• 429 — Too many requests; retry after the indicated delay.
• 502 — Response.

CLI: khotan pipelines redeploy

GET /api/v1/pipelines/{pipelineId}/setup

Get pipeline setup

Returns the pipeline's newest setup run, with its status, the reason for any status other than ready, the setup PR, and the live URL once it is ready. Returns { run: null } when setup never ran through Khotan.

Auth: API key required.

Operation ID: getPipelineSetup

Path parameters:

• pipelineId (string, required)

Responses:

• 200 — The newest run, or null.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan pipelines setup status

POST /api/v1/pipelines/{pipelineId}/setup

Start pipeline setup

Starts a cloud setup run for the pipeline: Khotan launches a cloud agent against the organization's repository with the intake, gives it a short-lived developer key, and merges its setup PR when every guard holds. Responds 202 with the run in status running; poll GET /api/v1/pipelines/{pipelineId}/setup to follow it. Requires an API key whose role includes developer, created by a member. Only one run may be running per organization. Pass an idempotencyKey to make retries safe.

Auth: API key required.

Operation ID: startPipelineSetup

Path parameters:

• pipelineId (string, required)

Request body (application/json, required):

• name (string, required)
• website (string, optional)
• logo (string | null, optional)
• idempotencyKey (string, optional) — Repeat a start with the same key to get the same run back instead of starting a second one.

Responses:

• 202 — The new run, in status running.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 403 — The caller is not permitted to perform this action.
• 404 — The resource was not found.
• 409 — Response.
• 429 — Too many requests; retry after the indicated delay.
• 503 — Response.

CLI: khotan pipelines setup

POST /api/v1/pipelines/{pipelineId}/setup/pull-request

Open or merge the pipeline's setup PR

Opens the setup PR from the pipeline's cursor/setup- branch into the default branch, or updates the open one, through Khotan's GitHub app. The setup script calls it when gh cannot. With merge: true, Khotan merges with a merge commit only when the caller is the running setup run's own key, the PR changes only the pipeline, its database package, bun.lock, khotan.bindings.json, and skills-lock.json, and every check on the head commit passed. A refused merge returns 409 with the guard's code and leaves the PR open.

Auth: API key required.

Operation ID: upsertPipelineSetupPullRequest

Path parameters:

• pipelineId (string, required)

Request body (application/json, required):

• title (string, required)
• body (string, required)
• merge (boolean, optional) — Merge the PR when every guard holds. Only the running setup run's own key can merge.

Responses:

• 200 — The setup PR, and whether it merged.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 403 — The caller is not permitted to perform this action.
• 404 — The resource was not found.
• 409 — Response.
• 429 — Too many requests; retry after the indicated delay.

GET /api/v1/pipelines/{pipelineId}/source

Download a pipeline's source

Returns the pipeline's source files (its subdirectory inside the org mono-root repo) as a JSON listing with paths rooted at the pipeline. Text files are returned as utf-8, binary files as base64. Responds 409 source_not_ready when the pipeline has no repo yet, and 413 source_too_large for sources past the inline download limit.

Auth: API key required.

Operation ID: getPipelineSource

Path parameters:

• pipelineId (string, required)

Responses:

• 200 — The pipeline's source files.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 409 — The pipeline exists but its source repository is not ready yet.
• 413 — The source is too large to download as a single response.
• 429 — Too many requests; retry after the indicated delay.
• 502 — Response.

CLI: khotan pipelines source

GET /api/v1/pipelines/{pipelineId}/env

List environment variables

Returns environment variable metadata (key, targets, type, last update) for the pipeline's provider project. Requires an API key whose role includes developer. Values are never included; use the reveal endpoint to fetch one decrypted value.

Auth: API key required.

Operation ID: listPipelineEnvVars

Path parameters:

• pipelineId (string, required)

Responses:

• 200 — Environment variable metadata, never values.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 409 — Response.
• 429 — Too many requests; retry after the indicated delay.
• 502 — Response.

CLI: khotan pipelines env list

POST /api/v1/pipelines/{pipelineId}/env

Bulk upsert environment variables

Creates or updates many environment variables for the given environments (defaults to all when target is omitted) in one request; other environments keep their value. Requires an API key whose role includes developer. Writes are not transactional: the response reports upsertedKeys and failedKeys, and earlier successful writes remain applied — retry the failed subset. Changes apply on the next run; trigger a redeploy to start one.

Auth: API key required.

Operation ID: bulkUpsertPipelineEnvVars

Path parameters:

• pipelineId (string, required)

Request body (application/json, required):

• variables (object[], required)
• target (array<"production" | "preview" | "development">, optional)

Responses:

• 200 — The partial result: which keys were upserted and which failed.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 409 — Response.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan pipelines env bulk-set

GET /api/v1/pipelines/{pipelineId}/env/{key}

Reveal an environment variable

Returns the decrypted value of one environment variable for a single environment (defaults to production; pass ?target=preview|development). Treat the value as a secret. Every reveal is audit-logged with the key name and caller; the value itself is never logged.

Auth: API key required.

Operation ID: revealPipelineEnvVar

Path parameters:

• pipelineId (string, required)
• key (string, required)

Query parameters:

• target ("production" | "preview" | "development", optional)

Responses:

• 200 — The decrypted value.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 409 — Response.
• 429 — Too many requests; retry after the indicated delay.
• 502 — Response.

CLI: khotan pipelines env reveal

PUT /api/v1/pipelines/{pipelineId}/env/{key}

Upsert an environment variable

Creates or updates one environment variable for the given environments (defaults to all when target is omitted); other environments keep their value. Changes apply on the next run; trigger a redeploy to start one.

Auth: API key required.

Operation ID: upsertPipelineEnvVar

Path parameters:

• pipelineId (string, required)
• key (string, required)

Request body (application/json, required):

• value (string, required)
• target (array<"production" | "preview" | "development">, optional)

Responses:

• 200 — The variable was written.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 409 — Response.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan pipelines env set

DELETE /api/v1/pipelines/{pipelineId}/env/{key}

Delete an environment variable

Removes one environment variable's value from the given environment (pass ?target=production|preview|development; omit to remove from all). Deleting a value that does not exist succeeds. Changes apply on the next run; trigger a redeploy to start one.

Auth: API key required.

Operation ID: deletePipelineEnvVar

Path parameters:

• pipelineId (string, required)
• key (string, required)

Query parameters:

• target ("production" | "preview" | "development", optional)

Responses:

• 200 — The variable was removed.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 409 — Response.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan pipelines env unset

GET /api/v1/pipelines/{pipelineId}/email-subscriptions

List a pipeline's email subscriptions

Lists this pipeline's mailbox subscriptions. Each delivers new-message notifications from a connected Gmail or Outlook mailbox directly to its delivery URL. Responses never include the Outlook client state.

Auth: API key required.

Operation ID: listPipelineEmailSubscriptions

Path parameters:

• pipelineId (string, required)

Responses:

• 200 — The pipeline's email subscriptions.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan pipelines email-subscriptions list

POST /api/v1/pipelines/{pipelineId}/email-subscriptions

Subscribe a pipeline to a mailbox

Subscribes this pipeline to a connected Gmail or Outlook mailbox so the provider delivers new-message notifications directly to deliveryUrl (https). Gmail: Khotan registers the mailbox watch and a Pub/Sub push subscription whose pushes carry a Google OIDC token. Outlook: Khotan creates a Microsoft Graph subscription — Graph first validates deliveryUrl by POSTing a validationToken query parameter that the receiver must echo as text/plain within 10 seconds, and every later notification carries the clientState returned here. Secret-bearing and never cached; recover a lost clientState from the client-state endpoint.

Auth: API key required.

Operation ID: createPipelineEmailSubscription

Path parameters:

• pipelineId (string, required)

Request body (application/json, required):

• emailIntegrationId (string, required)
• deliveryUrl (string, required)

Responses:

• 201 — The created subscription. For Outlook it includes the clientState secret.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 409 — Response.
• 429 — Too many requests; retry after the indicated delay.
• 502 — Response.

CLI: khotan pipelines email-subscriptions create

GET /api/v1/pipelines/{pipelineId}/email-subscriptions/{subscriptionId}

Get a pipeline's email subscription

Auth: API key required.

Operation ID: getPipelineEmailSubscription

Path parameters:

• pipelineId (string, required)
• subscriptionId (string, required)

Responses:

• 200 — The subscription.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan pipelines email-subscriptions get

DELETE /api/v1/pipelines/{pipelineId}/email-subscriptions/{subscriptionId}

Unsubscribe a pipeline from a mailbox

Stops delivery to this pipeline. Gmail: deletes the Pub/Sub push subscription and, when nothing else subscribes to that mailbox, stops the Gmail watch and removes the topic. Outlook: deletes the Microsoft Graph subscription (already-missing counts as deleted); returns 502 provider_error and keeps the subscription if Graph refuses, so the call can be retried.

Auth: API key required.

Operation ID: deletePipelineEmailSubscription

Path parameters:

• pipelineId (string, required)
• subscriptionId (string, required)

Responses:

• 200 — The subscription was removed.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.
• 502 — Response.

CLI: khotan pipelines email-subscriptions delete

GET /api/v1/pipelines/{pipelineId}/email-subscriptions/{subscriptionId}/client-state

Get a pipeline's Outlook subscription client state (secret)

Returns the Outlook subscription's clientState — the secret Microsoft Graph sends with every notification to the delivery URL. Compare it in constant time and reject notifications that don't match. Treat it as a secret. Returns 400 client_state_unsupported for Gmail subscriptions, which are verified by Pub/Sub OIDC instead.

Auth: API key required.

Operation ID: getPipelineEmailSubscriptionClientState

Path parameters:

• pipelineId (string, required)
• subscriptionId (string, required)

Responses:

• 200 — The subscription's client state. Secret-bearing.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

GET /api/v1/pipelines/{pipelineId}/oauth

Get pipeline OAuth status

Returns non-secret OAuth client status, effective redirect URIs, and setup availability.

Auth: API key required.

Operation ID: getPipelineOAuthStatus

Path parameters:

• pipelineId (string, required)

Responses:

• 200 — The OAuth client status.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan pipelines oauth status

DELETE /api/v1/pipelines/{pipelineId}/oauth

Disconnect pipeline OAuth

Revokes the OAuth client and removes its injected environment variables.

Auth: API key required.

Operation ID: disconnectPipelineOAuth

Path parameters:

• pipelineId (string, required)

Responses:

• 200 — The OAuth client was disconnected.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan pipelines oauth disconnect

POST /api/v1/pipelines/{pipelineId}/oauth/setup

Set up pipeline OAuth

Creates the OAuth client once and returns its plaintext secret. Returns a conflict when credentials already exist.

Auth: API key required.

Operation ID: setupPipelineOAuth

Path parameters:

• pipelineId (string, required)

Responses:

• 200 — The new OAuth credentials.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 409 — Response.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan pipelines oauth setup

POST /api/v1/pipelines/{pipelineId}/oauth/sync

Sync pipeline OAuth

Repairs redirect and environment configuration without rotating the client secret.

Auth: API key required.

Operation ID: syncPipelineOAuth

Path parameters:

• pipelineId (string, required)

Responses:

• 200 — The synchronized OAuth configuration.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 409 — Response.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan pipelines oauth sync

POST /api/v1/pipelines/{pipelineId}/oauth/rotate

Rotate pipeline OAuth secret

Invalidates the current secret, injects a new one, and optionally starts a fresh deployment.

Auth: API key required.

Operation ID: rotatePipelineOAuth

Path parameters:

• pipelineId (string, required)

Request body (application/json, required):

• redeploy (boolean, optional)

Responses:

• 200 — The rotated credentials and redeploy result.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 409 — Response.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan pipelines oauth rotate

PUT /api/v1/pipelines/{pipelineId}/oauth/redirect-uris

Replace pipeline OAuth redirect URIs

Replaces operator-managed redirect URIs while preserving the managed production callback.

Auth: API key required.

Operation ID: setPipelineOAuthRedirectUris

Path parameters:

• pipelineId (string, required)

Request body (application/json, required):

• redirectUris (string[], optional)

Responses:

• 200 — The effective redirect URI set.
• 400 — The request was malformed or failed validation.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 409 — Response.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan pipelines oauth set-redirects

POST /api/v1/pipelines/{pipelineId}/oauth/export

Export pipeline OAuth environment

Returns secret-bearing .env.local content for the existing OAuth client.

Auth: API key required.

Operation ID: exportPipelineOAuth

Path parameters:

• pipelineId (string, required)

Responses:

• 200 — The .env.local content.
• 401 — Authentication is missing or invalid.
• 404 — The resource was not found.
• 409 — Response.
• 429 — Too many requests; retry after the indicated delay.

CLI: khotan pipelines oauth export