API reference · API 1.0.0

Customers

Customers (companies) on this platform.

get /api/v1/customers

List customers

Operation customers_list · bearer token

The customers of this platform, in id order, archived ones included. The filters are exact and combine: short_name, gitlab_group, status. A list never contacts GitLab; read one customer with include=gitlab_status for its group's live state.

Parameters

Name	In	Type	Description
`short_name`	query	string \| null	Exact short name.
`gitlab_group`	query	string \| null	Exact GitLab group.
`status`	query	string \| null	one of `active`, `suspended`, `archived`
`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 customers.

application/json → CustomerPage

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/customers

Register a customer

Operation customers_create · bearer token

Creates the customer (with status active unless suspended is asked for) and its primary tenant in one transaction, then creates or adopts its GitLab group. A GitLab failure does not fail the request: the customer exists, and warnings says what is missing. 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

Name	In	Type	Description
`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 CustomerCreate

A new customer. Its primary tenant (slug = gitlab_group) is created with it, and its GitLab group is created or adopted.

Name	Type	Description
`billing_tier`	string	`INTERNAL`: not invoiced (ATAILA's own and reference customers); `PAYING`: invoiced. Default `INTERNAL`. one of `INTERNAL`, `PAYING` · default `"INTERNAL"`
`customer_index`	integer \| null	Omit to have the server allocate the next free index. min 1 · max 999
`default_email_tier`	integer	The mail service the customer's mailboxes are created on by default: `1`, `2` or `3`, as the portal's customer page names them. Default `3`. one of `1`, `2`, `3` · default `3`
`edition`	string	`sp` (the default): a customer of this multi-tenant platform; `enterprise`: a customer with a single-tenant installation of its own. Frozen after create. one of `sp`, `enterprise` · default `"sp"`
`gitlab_group`required	string	Also the primary tenant's slug, so the tenant slug rule applies: Lowercase letters, digits and '-', starting with a letter, 2-30 characters. Frozen after create. pattern `^[a-z][a-z0-9-]{1,29}$`
`long_name`required	string	The customer's full name. min length 3 · max length 80
`notes`	string \| null	Free text for operators, up to 2000 characters. max length 2000
`primary_contact_email`required	string (email)	An e-mail address. Stored and returned normalised: the domain is lower-cased (and internationalised domains are converted to their canonical form), the local part (before `@`) keeps its case exactly as sent, surrounding whitespace is dropped, and a `Name <address>` form is reduced to the address. `Pat@Example.COM` is therefore returned as `Pat@example.com`; compare with the domain case-folded to avoid a perpetual diff.
`primary_contact_name`required	string	The name of the customer's primary contact. min length 2 · max length 80
`short_name`required	string	Upper-case letters and digits, starting with a letter, 2-16 characters (e.g. `ACME`). Frozen after create. min length 2 · max length 16 · pattern `^[A-Z][A-Z0-9]{1,15}$`
`status`	string	`active` (default) or `suspended`. one of `active`, `suspended` · default `"active"`

Responses

201

The customer was registered.

application/json → Customer

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 (customer_index_taken, short_name_taken, gitlab_group_taken), the group name collides with another customer's (gitlab_group_collision), or no index is left (customer_index_exhausted).

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/customers/{customer_id}

One customer

Operation customers_get · bearer token

One customer by id, archived ones included. With include=gitlab_status the customer's GitLab group is looked up live (read-only); without it nothing outside the platform is contacted.

Parameters

Name	In	Type	Description
`customer_id`required	path	string	The customer's id (`id` on a customer). pattern `^[1-9][0-9]{0,8}$`
`include`	query	`"gitlab_status"` \| null	`gitlab_status`: also ask GitLab for the customer's group. Null with a warning when GitLab cannot be reached.

Responses

200

The customer.

application/json → Customer

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 customer (customer_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/customers/{customer_id}

Change a customer

Operation customers_update · bearer token

Only the members in the body change. customer_index, short_name, gitlab_group and edition are frozen: sending the current value is accepted, a different one is a 422. An archived customer cannot be changed, and status can be set only to active or suspended, so an archived customer cannot be restored through v1.

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

Name	In	Type	Description
`customer_id`required	path	string	The customer's id (`id` on a customer). pattern `^[1-9][0-9]{0,8}$`

Request bodyrequired

application/jsonapplication/merge-patch+json

Schema CustomerPatch

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. Only notes is nullable. archived is not a settable status: archiving is DELETE /customers/{id}.

Name	Type	Description
`billing_tier`	string \| null	`INTERNAL`: not invoiced (ATAILA's own and reference customers); `PAYING`: invoiced. one of `INTERNAL`, `PAYING`
`customer_index`	integer \| null	Frozen.
`default_email_tier`	integer \| null	The mail service the customer's mailboxes are created on by default: `1`, `2` or `3`, as the portal's customer page names them. one of `1`, `2`, `3`
`edition`	string \| null	Frozen. one of `sp`, `enterprise`
`gitlab_group`	string \| null	Frozen.
`long_name`	string \| null	The customer's full name. min length 3 · max length 80
`notes`	string \| null	Free text for operators, up to 2000 characters. null clears it. max length 2000
`primary_contact_email`	string (email) \| null	An e-mail address. Stored and returned normalised: the domain is lower-cased (and internationalised domains are converted to their canonical form), the local part (before `@`) keeps its case exactly as sent, surrounding whitespace is dropped, and a `Name <address>` form is reduced to the address. `Pat@Example.COM` is therefore returned as `Pat@example.com`; compare with the domain case-folded to avoid a perpetual diff.
`primary_contact_name`	string \| null	The name of the customer's primary contact. min length 2 · max length 80
`short_name`	string \| null	Frozen.
`status`	string \| null	`active` or `suspended`; archiving is `DELETE /customers/{id}`. one of `active`, `suspended`

Responses

200

The customer after the change.

application/json → Customer

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 customer (customer_not_found).

application/jsonapplication/problem+json → Problem

Headers: X-Request-ID
409

The customer is archived (customer_archived).

application/jsonapplication/problem+json → Problem

Headers: X-Request-ID
422

A frozen key was changed (immutable_field), 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/customers/{customer_id}

Archive a customer

Operation customers_delete · bearer token

Archives the customer: the row, its keys, its tenants and its GitLab group stay. Archiving an archived customer succeeds and changes nothing. Archiving is final through v1: no operation restores an archived customer, and its customer_index, short_name and gitlab_group stay taken.

Parameters

Name	In	Type	Description
`customer_id`required	path	string	The customer's id (`id` on a customer). pattern `^[1-9][0-9]{0,8}$`

Responses

204

The customer is archived.

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 customer (customer_not_found).

application/jsonapplication/problem+json → Problem

Headers: X-Request-ID
409

Projects still exist under the customer, retired ones included (customer_has_projects). blockers counts them: {"projects": n}. conflict: the customer changed while being archived; 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

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