API reference · API 1.0.0

Releases

Release promotions, release state and the PROD lock.

get /api/v1/projects/{project_id}/prod-lock

The PROD data lock

Operation prod_lock_get · bearer token

While locked, no data copy may target PROD. Code promotion is not affected.

Parameters

NameInTypeDescription
project_idrequired path string

The project's id.

pattern ^[1-9][0-9]{0,8}$

Responses

  • 200

    The PROD data lock.

    application/json → ProdLock
    Headers: X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 404

    No such project, or outside your scope (project_not_found).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 503

    The platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
put /api/v1/projects/{project_id}/prod-lock

Set the PROD data lock

Operation prod_lock_put · bearer token

The lock protects PROD DATA: while it is set, the portal refuses every data copy into PROD, so PROD stays the source of truth for its data. It does NOT block code promotion into PROD.

{"locked": true} locks. Unlocking needs confirm_unlock equal to the project's short name. Setting the state it already has changes nothing (the lock keeps its time and author).

Parameters

NameInTypeDescription
project_idrequired path string

The project's id.

pattern ^[1-9][0-9]{0,8}$

Request bodyrequired

application/json

Schema ProdLockPut

The PROD data lock's new state. Setting the state it already has changes nothing.

NameTypeDescription
confirm_unlock string | null

Required to UNLOCK: the project's short name, exactly.

max length 64
lockedrequired boolean

true sets the lock; false releases it and needs confirm_unlock.

Responses

  • 200

    The PROD data lock after the change.

    application/json → ProdLock
    Headers: X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 404

    No such project, or outside your scope (project_not_found).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 409

    The project is retired (project_retired): its PROD lock no longer changes.

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 422

    Unlocking without confirm_unlock equal to the project's short name (unlock_not_confirmed).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 503

    The platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
get /api/v1/projects/{project_id}/release-operations

Release history of a project

Operation release_operations_list · bearer token

Newest first. Includes the data copies booked in the portal.

Parameters

NameInTypeDescription
project_idrequired path string

The project's id.

pattern ^[1-9][0-9]{0,8}$
status query string | null

Only operations in this status.

one of pending, awaiting_approval, running, succeeded, failed
target_env query string | null
one of sandbox, dev, uat, prod
component query string | null

Excludes data copies (no component).

one of app-api, www
limit query integer

Page size.

min 1 · max 200 · default 50
cursor query string | null

next_cursor from the previous page; omit it for the first page. A cursor this list did not issue is a 400 invalid_cursor.

Responses

  • 200

    One page of release operations, newest first.

    application/json → ReleaseOperationPage
    Headers: X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 404

    No such project, or outside your scope (project_not_found).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 503

    The platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
post /api/v1/projects/{project_id}/release-promotions

Request a promotion

Operation release_promotions_create · bearer token

Books a promotion of one component into one environment and answers 202 with an operation (release:<id>) and its Location. Poll GET /operations/{id} until succeeded or failed.

  • dev and uat start at once.
  • dev promotions deploy a named build; the API cannot verify it exists before dispatch. Its version is required and is not checked against any reported version (DEV has no environment below it).
  • prod is a REQUEST: the operation stays awaiting_approval until a person approves or rejects it in the portal's release management. This API cannot approve, reject, release express or copy data. A rejection ends it as failed with the reason. Approval needs no second person when the approver writes a note; a request made with a token counts as made by the token's owner and by whoever minted it.

Kubernetes projects only. The version promoted into uat or prod is the one the environment below last reported (dev for uat, uat for prod). Send an Idempotency-Key: a retried request then never books a second deployment.

Parameters

NameInTypeDescription
project_idrequired path string

The project's id.

pattern ^[1-9][0-9]{0,8}$
Idempotency-Key header string

Makes a retry safe: for 24 hours, the same key with the same request (method, path, query and body) answers with the stored response (Idempotent-Replayed: true) instead of doing the work again. The same key with a different request is a 409 idempotency_key_reused; while the first request is still running it is a 429 idempotency_request_in_progress with Retry-After. 1-255 printable characters without spaces (400 invalid_idempotency_key otherwise); a UUID is a good key. Keys are scoped to the calling account.

min length 1 · max length 255 · pattern ^[!-~]+$

Request bodyrequired

application/json

Schema ReleasePromotionCreate

Request a promotion of one component into one environment.

dev deploys a named build and needs version; the API cannot verify that the build exists before dispatch. uat and prod promote what the environment below LAST REPORTED running (dev for uat, uat for prod): omit version to take it, or give it and it must be that version.

NameTypeDescription
componentrequired string

What to promote: app-api (the application and its API) or www (the web site).

one of app-api, www
target_envrequired string

Where to: dev, uat or prod. A prod promotion waits for a person to approve it in the portal.

one of dev, uat, prod
version string | null

Required for dev, where it names a build that the API cannot verify exists before dispatch. For uat and prod: omitted means the version the source environment last reported; given, it must equal that version (422 version_not_at_source otherwise).

pattern ^[A-Za-z0-9_][A-Za-z0-9_.-]{0,63}$

Responses

  • 202

    The promotion was booked: poll the operation.

    application/json → Operation
    Headers: Idempotent-Replayed, Location, X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 404

    No such project, or outside your scope (project_not_found).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 409

    The project is retired (project_retired: a retired project takes no release), or the Idempotency-Key already booked a different operation (idempotency_key_reused).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 422

    A VM project (vm_projects_unsupported); the component does not exist (component_not_enabled); the version is not what the source environment last reported, or it reports none (version_not_at_source); a dev promotion without a version (version_required).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 503

    The platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
get /api/v1/projects/{project_id}/release-state

Release state of a project

Operation release_state_get · bearer token

Per environment and component, the version a release pipeline LAST REPORTED, when and by whom — recorded when a deploy reports success, not probed live. Also the PROD DATA lock and the operations still open.

Parameters

NameInTypeDescription
project_idrequired path string

The project's id.

pattern ^[1-9][0-9]{0,8}$

Responses

  • 200

    The release state.

    application/json → ReleaseState
    Headers: X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 404

    No such project, or outside your scope (project_not_found).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 503

    The platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
get /api/v1/release-operations/{release_operation_id}

One release operation

Operation release_operations_get · bearer token

One release operation (a promotion and what became of it) by id, as recorded. The same one is the operation release:<id> at GET /operations/{id}. Only operations of projects within the caller's reach are visible (for a token, every project); any other id answers 404.

Parameters

NameInTypeDescription
release_operation_idrequired path string
pattern ^[1-9][0-9]{0,8}$

Responses

  • 200

    The release operation.

    application/json → ReleaseOperation
    Headers: X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 404

    No such operation, or its project is outside your scope (release_operation_not_found).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 503

    The platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID

Rendered from openapi-v1.json, platform release 1.0.187. Your installation serves the contract of its own version at /api/v1/openapi.json.