Create a repository (deprecated path)
POST /projects
Deprecated. Use /repositories instead; it is the same handler, so the wire shapes are identical.
A pure cloud-DB insert — the cloud is secret-blind and does not touch git. slug is derived from name when omitted.
Constraints not expressible in JSON Schema, enforced at runtime:
- Preview-port names must be unique within the preview-port list, and each must match
^[a-z0-9][a-z0-9_-]{0,62}$. - A preview port’s URL environment-variable name may be empty or whitespace-only, which means unset rather than a validation failure.
- Environment-variable keys must be unique within the repository environment declaration list.
May require, depending on the request: projects.write, projects.env.configure
projects.write always; projects.env.configure additionally when the body supplies a non-empty env, and projects.env.values.write when a declaration carries a defaultValue.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Header Parameters
Section titled “Header Parameters ”Org scope: me or an org slug. Absent means the caller’s active/personal org. It selects the workspace used for permission checks and for most resource filters; operation-specific access rules still apply.
Request Body required
Section titled “Request Body required ”object
object
object
Responses
Section titled “ Responses ”Successful response.
object
object
ULID
JSON-encoded PreviewPortDeclaration[] — a string, not an array
JSON-encoded ProjectEnvDeclaration[] — schema only, never values
Epoch milliseconds
Epoch milliseconds
BAD_SLUG — no slug could be derived.
BAD_JSON — the body is not valid JSON, or INVALID_REQUEST — the decoded body does not match the route’s request schema.
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
UNAUTHORIZED — missing or invalid token, or an org-scoped API key (only user-scoped keys are accepted).
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
PLAN_LIMIT — the workspace is at its repository cap.
PLAN_LIMIT — the workspace’s plan does not include API access. Every API-key call can return this; session-token calls never do.
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
ENV_VALUES_FORBIDDEN — a defaultValue without projects.env.values.write.
FORBIDDEN (lacking the required permission) or SCOPE_REQUIRED (no workspace, or a membership change in progress).
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
SCOPE_REQUIRED — the x-uai-org scope names a workspace that does not exist, or one the caller is not a member of. The two are deliberately indistinguishable: a 403 would confirm the workspace exists.
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
PROJECT_SLUG_TAKEN — slug already used.
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
PROJECT_READBACK_FAILED — inserted but unreadable.
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
SCOPE_REQUIRED — membership reconciliation required, or membership verification unavailable.
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan