API reference · API 1.0.0

Projects

Projects, provisioning and project members.

get /api/v1/projects

List projects

Operation projects_list · bearer token

Slim items: no outputs. Read one project for those.

Parameters

NameInTypeDescription
tenant_id query string | null

Only this tenant's.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
customer_id query string | null

Only this customer's, across its tenants.

pattern ^[1-9][0-9]{0,8}$
status query string | null
one of planned, provisioning, active, paused, retired
short_name query string | null

Exact short name.
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 projects.

    application/json → ProjectPage
    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
  • 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

Register a project

Operation projects_create · bearer token

Registers the project and compiles its manifest. Provisions NOTHING: start that with POST /projects/{id}/provisioning. project_index is allocated when omitted. A token that creates a project is recorded as registered_by. Send an Idempotency-Key to make a retry safe: a retry with the same key and request gets the first answer and changes nothing.

Parameters

NameInTypeDescription
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 ProjectCreate

A new project: registered and its manifest compiled. Provisions nothing: POST /projects/{id}/provisioning does.

NameTypeDescription
allow_public_https_egress boolean

Kubernetes projects: allow egress to public HTTPS.

default false
api_exposure string

Who reaches the PROD API: INTERNAL_ONLY (default) or PUBLIC. The UAT and DEV APIs are never public.

one of INTERNAL_ONLY, PUBLIC · default "INTERNAL_ONLY"
app_gateway string

shared rides the environment's app gateway; dedicated gets its own.

one of shared, dedicated · default "shared"
deployment_backend string

k8s (default): namespaces on the shared Kubernetes clusters; vm: virtual machines of its own. Frozen.

one of vm, k8s · default "k8s"
description string | null

Free text, up to 2000 characters.

max length 2000
enable_ai boolean

An AI endpoint at ai.<primary_domain>. Also allows outbound HTTPS to the internet, as allow_public_https_egress does.

default false
enable_cache boolean

An in-memory key-value cache.

default false
enable_dr_db_replica boolean

A disaster-recovery replica of the PROD database.

default true
enable_dr_object_storage_mirror boolean

A disaster-recovery mirror of the PROD object storage.

default true
enable_fullstack_app boolean

An application: its front end at app.<primary_domain> and its API at api.<primary_domain>, in PROD, UAT and DEV.

default true
enable_iis boolean

IIS/.NET hosting. VM backend only.

default false
enable_mssql boolean

SQL Server. VM backend only.

default false
enable_nas_object_storage_replication boolean

Replication of the object storage to the central store: recorded, not acted on yet.

default false
enable_object_storage boolean

Object storage for the project; false provisions none (a database-only project).

default true
enable_static_site boolean

A web site at www.<primary_domain> (and uat.www., dev.www.), seeded from www_template.

default true
enable_uat_app_public boolean

Make the UAT front end (uat.app.) reachable from the internet, e.g. to share a preview. DEV is never public.

default false
enable_uat_www_public boolean

Make the UAT web site (uat.www.) reachable from the internet.

default false
enable_web_www boolean

The web site ships from its own <gitlab_repo_slug>-www repository. Provisioning does not read it: the web site, its repository and its stages follow enable_static_site alone. With false, the platform's security scans leave the web site out, and a project with no application drops out of the traffic views. Keep it true (the default) unless the web site is not built from that repository.

default true
frontend_exposure string

Who reaches the PROD front end: PUBLIC (the internet; default) or INTERNAL_ONLY.

one of INTERNAL_ONLY, PUBLIC · default "PUBLIC"
frontend_variant string

The front-end framework the application is generated with: react (default), angular, vue or nuxt4.

one of react, angular, vue, nuxt4 · default "react"
github_repo_url string | null

A GitHub repository URL, recorded in the project's manifest as its mirror.
github_user string | null

A GitHub user name, recorded with the project.
gitlab_repo_slugrequired string

The repository name in the customer's GitLab group; unique within the customer. Frozen.

pattern ^[a-z][a-z0-9-]{1,40}$
has_mobile boolean

The project has a mobile app. Its PROD API is then public whatever api_exposure says: the app calls it from the internet.

default false
import_existing_repo boolean

The GitLab repository already holds code: provisioning does not seed it from the template.

default false
long_namerequired string

The project's display name, 2-60 characters. Double quotes, apostrophes, backslashes and control characters are refused: the name is written into the project's generated files.

min length 2 · max length 60
mssql_edition string

The SQL Server edition PROD and UAT run, with enable_mssql: express (default; free), standard or enterprise (licensed through the platform operator).

one of express, standard, enterprise · default "express"
network_only boolean

Register the network zone only: no app, no web site. Forces enable_static_site and enable_fullstack_app off. Frozen.

default false
primary_domainrequired string

The domain the project's sites are named under (www., app., api., ai.). Frozen.

max length 253
prod_object_storage_disks_per_vm integer

Data disks per PROD object storage node.

one of 1, 2 · default 2
prod_object_storage_node_count integer

PROD object storage nodes. With enable_object_storage, nodes times prod_object_storage_disks_per_vm must be at least 4.

one of 2, 4 · default 2
project_index integer | null

The third octet of the project's networks, estate-wide unique. Omit it and the server allocates one above the highest in use (never below 4). Frozen.

min 1 · max 99
short_namerequired string

Lowercase letters and digits, 2-11, starting with a letter. Estate-wide unique. Frozen.

pattern ^[a-z][a-z0-9]{1,10}$
tenant_idrequired string

The owning tenant. Frozen.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
windows_vm_count_dev integer

Windows Server VMs in DEV, 0-10. VM backend only.

min 0 · max 10 · default 0
windows_vm_count_prod integer

Windows Server VMs in PROD, 0-10. VM backend only.

min 0 · max 10 · default 0
windows_vm_count_uat integer

Windows Server VMs in UAT, 0-10. VM backend only.

min 0 · max 10 · default 0
www_template string

What seeds the web site's repository: template-www (an information site; default) or template-blog (articles in Markdown, with feeds). Ignored without enable_static_site.

one of template-www, template-blog · default "template-www"

Responses

  • 201

    The project was registered.

    application/json → Project
    Headers: Idempotent-Replayed, 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
  • 409

    A unique key is taken, or no index is left (project_index_exhausted), or the customer is archived (customer_archived). The unique keys are checked in ONE fixed order — short_name, project_index (when sent), primary_domain, gitlab_repo_slug — and the FIRST one taken is the answer: code is <key>_taken and field names it. conflicts lists EVERY taken key in that order, each as {field, code, project_id} (project_id: the project holding it, null when a concurrent create took it). Retired projects keep their keys, so a retired project's values stay taken.

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

    No such tenant (tenant_not_found), an impossible combination (invalid_combination), the manifest compiler refused the input (manifest_refused, windows_requires_vm_backend; detail is its message), or the body is invalid.

    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}

One project

Operation projects_get · bearer token

One project by id, retired ones and ATAILA's own platform projects (is_self) included, with outputs: the names its provisioning produces or will produce (public URLs, repositories, namespaces). Provisioning progress is GET /projects/{id}/provisioning.

Parameters

NameInTypeDescription
project_idrequired path string

The project's id (id on a project).

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

Responses

  • 200

    The project.

    application/json → Project
    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 (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
patch /api/v1/projects/{project_id}

Change a project

Operation projects_update · bearer token

Changes the record and recompiles its manifest; dispatches nothing. The provisioning stages the change leaves stale are marked and returned as stale_stages; POST /projects/{id}/provisioning re-applies exactly those. Only a stage already done can be stale: one never applied is applied with the new manifest by the next start anyway. Frozen: project_index, short_name, gitlab_repo_slug, tenant_id, deployment_backend, network_only, primary_domain (the current value is accepted, a different one is a 422). The create rules are checked on the merged result.

The body is a JSON Merge Patch (RFC 7396), sent as application/merge-patch+json or application/json: a member that is omitted is left unchanged, and a member set to null clears that field where clearing is allowed (the schema marks those fields nullable; null for any other field is a 422).

Parameters

NameInTypeDescription
project_idrequired path string

The project's id (id on a project).

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

Request bodyrequired

application/jsonapplication/merge-patch+json

Schema ProjectPatch

JSON Merge Patch (RFC 7396): a member that is omitted keeps its current value; a member sent as null clears the field when the field is nullable (the schema marks it so), and null for any other field is a 422. A "" is a value (an empty string), not a clear. Frozen members are accepted only with the current value. status is not writable in v1.

NameTypeDescription
allow_public_https_egress boolean | null

Kubernetes projects: allow egress to public HTTPS.
api_exposure string | null

Who reaches the PROD API: INTERNAL_ONLY (default) or PUBLIC. The UAT and DEV APIs are never public.

one of INTERNAL_ONLY, PUBLIC
app_gateway string | null

shared rides the environment's app gateway; dedicated gets its own.

one of shared, dedicated
deployment_backend string | null

Frozen.

one of vm, k8s
description string | null

null clears it.

max length 2000
enable_ai boolean | null

An AI endpoint at ai.<primary_domain>. Also allows outbound HTTPS to the internet, as allow_public_https_egress does.
enable_cache boolean | null

An in-memory key-value cache.
enable_dr_db_replica boolean | null

A disaster-recovery replica of the PROD database.
enable_dr_object_storage_mirror boolean | null

A disaster-recovery mirror of the PROD object storage.
enable_fullstack_app boolean | null

An application: its front end at app.<primary_domain> and its API at api.<primary_domain>, in PROD, UAT and DEV.
enable_iis boolean | null

IIS/.NET hosting. VM backend only.
enable_mssql boolean | null

SQL Server. VM backend only.
enable_nas_object_storage_replication boolean | null

Replication of the object storage to the central store: recorded, not acted on yet.
enable_object_storage boolean | null

Object storage for the project; false provisions none (a database-only project).
enable_static_site boolean | null

A web site at www.<primary_domain> (and uat.www., dev.www.), seeded from www_template.
enable_uat_app_public boolean | null

Make the UAT front end (uat.app.) reachable from the internet, e.g. to share a preview. DEV is never public.
enable_uat_www_public boolean | null

Make the UAT web site (uat.www.) reachable from the internet.
enable_web_www boolean | null

The web site ships from its own <gitlab_repo_slug>-www repository. Provisioning does not read it: the web site, its repository and its stages follow enable_static_site alone. With false, the platform's security scans leave the web site out, and a project with no application drops out of the traffic views. Keep it true (the default) unless the web site is not built from that repository.
frontend_exposure string | null

Who reaches the PROD front end: PUBLIC (the internet; default) or INTERNAL_ONLY.

one of INTERNAL_ONLY, PUBLIC
frontend_variant string | null

The front-end framework the application is generated with: react (default), angular, vue or nuxt4.

one of react, angular, vue, nuxt4
github_repo_url string | null

A GitHub repository URL, recorded in the project's manifest as its mirror. null clears it.
github_user string | null

A GitHub user name, recorded with the project. null clears it.
gitlab_repo_slug string | null

Frozen.
has_mobile boolean | null

The project has a mobile app. Its PROD API is then public whatever api_exposure says: the app calls it from the internet.
import_existing_repo boolean | null

The GitLab repository already holds code: provisioning does not seed it from the template.
long_name string | null

The project's display name, 2-60 characters. Double quotes, apostrophes, backslashes and control characters are refused: the name is written into the project's generated files.

min length 2 · max length 60
mssql_edition string | null

The SQL Server edition PROD and UAT run, with enable_mssql: express (default; free), standard or enterprise (licensed through the platform operator).

one of express, standard, enterprise
network_only boolean | null

Frozen.
primary_domain string | null

Frozen.
prod_object_storage_disks_per_vm integer | null

Data disks per PROD object storage node.

one of 1, 2
prod_object_storage_node_count integer | null

PROD object storage nodes. With enable_object_storage, nodes times prod_object_storage_disks_per_vm must be at least 4.

one of 2, 4
project_index integer | null

Frozen.
short_name string | null

Frozen.
tenant_id string | null

Frozen.
windows_vm_count_dev integer | null

Windows Server VMs in DEV, 0-10. VM backend only.

min 0 · max 10
windows_vm_count_prod integer | null

Windows Server VMs in PROD, 0-10. VM backend only.

min 0 · max 10
windows_vm_count_uat integer | null

Windows Server VMs in UAT, 0-10. VM backend only.

min 0 · max 10
www_template string | null

What seeds the web site's repository: template-www (an information site; default) or template-blog (articles in Markdown, with feeds). Ignored without enable_static_site.

one of template-www, template-blog

Responses

  • 200

    The project after the change, with the stages it left stale.

    application/json → ProjectUpdated
    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 (project_not_found).

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

    An ATAILA platform project (platform_project_read_only), a retired one (project_retired), or the project's tenant has no customer any more (tenant_has_no_customer).

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

    A frozen key was changed (immutable_field), an impossible combination (invalid_combination), a compiler refusal (manifest_refused, windows_requires_vm_backend), or the body is invalid.

    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
delete /api/v1/projects/{project_id}

Retire a project

Operation projects_delete · bearer token

Retires the project: status becomes retired and that is all. Its project_index, short_name and primary_domain stay reserved, and nothing on the substrate is touched — no VM, DNS record, secrets store path or repository is removed. There is no way to wipe or tear down a project through this API. Retiring a retired project is a 204.

Parameters

NameInTypeDescription
project_idrequired path string

The project's id (id on a project).

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

Responses

  • 204

    The project is retired.

    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

    A token created without allow_destroy (destroy_not_allowed). Also: 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 (project_not_found).

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

    An ATAILA platform project (platform_project_read_only), an orchestration is running on it (orchestration_in_progress), or it changed while being retired and could not be (project_not_retirable; retry).

    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}/members

A project's members

Operation project_members_list · bearer token

The people given a role on this one project, in user_id order. Tenant members reach the project through the tenant and are not listed here.

Parameters

NameInTypeDescription
project_idrequired path string

The project's id (id on a project).

pattern ^[1-9][0-9]{0,8}$
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 the project's members.

    application/json → ProjectMemberPage
    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 (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/projects/{project_id}/members/{user_id}

One project member

Operation project_members_get · bearer token

One person's role on the project. 404 member_not_found when they have no project-level role (a tenant member may still reach the project).

Parameters

NameInTypeDescription
user_idrequired path string
project_idrequired path string

The project's id (id on a project).

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

Responses

  • 200

    The project member.

    application/json → ProjectMember
    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 (project_not_found) or member (member_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}/members/{user_id}

Add a member or change their role

Operation project_members_put · bearer token

201 when the membership was created, 200 when an existing one was set. gitlab_role is recorded and NOT enforced: nothing is changed in GitLab.

Parameters

NameInTypeDescription
user_idrequired path string
project_idrequired path string

The project's id (id on a project).

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

Request bodyrequired

application/json

Schema ProjectMemberPut

The member's role on the project.

NameTypeDescription
gitlab_role string | null

Recorded, not enforced. maintainer is refused for a person who is not ATAILA staff.

one of guest, reporter, developer, maintainer
role string

owner, admin, developer (default), member or viewer.

one of owner, admin, developer, member, viewer · default "developer"

Responses

  • 200

    The existing member's role was set.

    application/json → ProjectMember
    Headers: X-Request-ID
  • 201

    The member was added.

    application/json → ProjectMember
    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 (project_not_found) or user (user_not_found).

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

    An ATAILA platform project (platform_project_read_only), a retired one (project_retired), or the user may not be a member (member_not_eligible: only ATAILA staff and members of a tenant of the project's customer may).

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

    gitlab_role above the customer cap (gitlab_role_above_cap), or the body is invalid.

    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
delete /api/v1/projects/{project_id}/members/{user_id}

Remove a member

Operation project_members_delete · bearer token

Removes the membership. Not destroy-gated: it needs the write permission only. Allowed on a retired project.

Parameters

NameInTypeDescription
user_idrequired path string
project_idrequired path string

The project's id (id on a project).

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

Responses

  • 204

    The member was removed.

    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 (project_not_found) or member (member_not_found).

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

    An ATAILA platform project (platform_project_read_only).

    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}/provisioning

A project's provisioning state

Operation project_provisioning_get · bearer token

Read from the database only. converged is true when every stage is done and none is stale; provisioned additionally requires that no stage was simulated. On a platform whose dispatch_mode is dryrun nothing is ever executed and provisioning never completes; under simulate stages are marked done without running, so converged can be true while provisioned is false.

Parameters

NameInTypeDescription
project_idrequired path string

The project's id (id on a project).

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

Responses

  • 200

    The provisioning state.

    application/json → Provisioning
    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 (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}/provisioning

Start provisioning

Operation project_provisioning_start · bearer token

Starts the stage engine and answers 202 with an operation (provision:<id>) to poll at GET /operations/{id} (also the Location header). When stages are stale it re-applies exactly those (apply-pending); otherwise it applies every stage not yet done (apply-all). The operation is awaiting_operator when a stage needs a person in the portal, and never succeeds on a dryrun platform; on a simulate platform it succeeds with simulated: true and provisions nothing. Send an Idempotency-Key: a retry with the same key gets the same operation and never starts a second orchestration.

Parameters

NameInTypeDescription
project_idrequired path string

The project's id (id on a project).

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 ^[!-~]+$

Responses

  • 202

    Provisioning started: 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 (project_not_found).

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

    An ATAILA platform project (platform_project_read_only), a retired one (project_retired), or an orchestration already holds the project (orchestration_in_progress; operation_id names it).

    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}/stages

A project's provisioning stages

Operation project_stages_list · bearer token

The stage grid of the portal's Plan page, read-only and from the database only.

Parameters

NameInTypeDescription
project_idrequired path string

The project's id (id on a project).

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

Responses

  • 200

    The stage grid.

    application/json → StageGrid
    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 (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

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