Update a repository

PATCH

/repositories/{id}

Production

Partial update. Edits apply to the NEXT task: every task start reads the row fresh, and running tasks keep the configuration they began with. At least one field must be provided.

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 env is present in the body, including an empty array, and projects.env.values.write when it changes a defaultValue.

Authorizations

bearerAuth

Parameters

Path Parameters

required

string

Resource ULID.

Header Parameters

x-uai-org

string

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

object

>= 1 properties

repoUrl

string

>= 1 characters /\S/

name

string

>= 1 characters <= 64 characters /\S/

slug

string

>= 1 characters <= 64 characters /^(?!files$)(?![0-9a-z]{26}$)[a-z0-9-]+$/

defaultPrompt

string

<= 8000 characters

previewPorts

Array<object>

<= 20 items

object

name

required

string

>= 1 characters <= 63 characters /^[a-z0-9][a-z0-9_-]{0,62}$/

containerPort

required

integer

>= 1 <= 65535

urlEnv

string

<= 64 characters /^[A-Za-z_][A-Za-z0-9_]*$/

env

Array<object>

object

key

required

string

>= 1 characters /^[A-Za-z_][A-Za-z0-9_]*$/

label

required

string

>= 1 characters /\S/

secret

boolean

defaultValue

string

toolVersions

string

extra

string

Responses

200

Successful response.

object

project

required

object

required

ULID

string

ownerOrgId

required

string

ownerUserId

required

string

name

required

string

slug

required

string

repoUrl

required

string

defaultPrompt

required

string

previewPorts

required

JSON-encoded PreviewPortDeclaration[] — a string, not an array

string

env

required

JSON-encoded ProjectEnvDeclaration[] — schema only, never values

string

toolVersions

required

string | null

extra

required

string | null

createdAt

required

Epoch milliseconds

integer

updatedAt

required

Epoch milliseconds

integer

400

BAD_JSON — the body is not valid JSON, or INVALID_REQUEST — the decoded body does not match the route’s request schema.

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer
null

integer

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

401

UNAUTHORIZED — missing or invalid token, or an org-scoped API key (only user-scoped keys are accepted).

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer
null

integer

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

402

PLAN_LIMIT — the workspace’s plan does not include API access. Every API-key call can return this; session-token calls never do.

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer
null

integer

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

403

ENV_VALUES_FORBIDDEN: a defaultValue changed without projects.env.values.write.

FORBIDDEN (lacking the required permission) or SCOPE_REQUIRED (no workspace, or a membership change in progress).

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer
null

integer

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

404

PROJECT_NOT_FOUND.

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

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer
null

integer

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

409

PROJECT_SLUG_TAKEN, or ENV_KEYS_CHANGED: env names other keys than the repository’s listed ones. env may edit labels, defaults and order; keys are added and removed on their own (POST and DELETE /api/repositories/{id}/env/keys).

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer
null

integer

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

503

SCOPE_REQUIRED — membership reconciliation required, or membership verification unavailable.

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer
null

integer

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

Update a repository

Authorizations

Parameters

Path Parameters

Header Parameters

Request Body required

Responses

200

400

401

402

403

404

409

503

Request Body^required