> For the complete documentation index, see [llms.txt](https://docs.khotan.com/llms.txt). A markdown version of any page is available at its `index.md` URL. # Pipelines `/api/v1` operations for pipelines. See [HTTP API](/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`