Set or clear a repository's guidance

PUT

/projects/{projectId}/repositories/{repositoryId}/guidance

curl --request PUT \
  --url https://zkao.io/api/v1/projects/example/repositories/example/guidance \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "content": "example", "expectedContent": "example" }'

• Production
• Staging

Requires scope: guidance:write. Sets content as the repository’s guidance (or clears it with null), recording a revision. Writing the same content that is already stored is a no-op (unchanged: true, no revision). Pass expectedContent for an optimistic compare-and-set: omit it for last-writer-wins, or send the content you last read (or null for “currently cleared”) to get a 409 instead of clobbering a concurrent change.

Authorizations

• bearerAuth

Parameters

Path Parameters

projectId

required

string

repositoryId

required

string

Request Body^required

Media typeapplication/json

object

content

required

New guidance content; null clears it.

string | null

<= 100000 characters

expectedContent

Optional compare-and-set. Omit for last-writer-wins. Send the content you last read (or null for “currently cleared”) to receive a 409 if the guidance changed underneath you instead of overwriting it.

string | null

Example^generated

{
  "content": "example",
  "expectedContent": "example"
}

Responses

200

OK

Media typeapplication/json

object

repositoryId

required

string

revisionId

required

The recorded revision id, or null on a no-op write.

string | null

unchanged

required

True when the content already matched (no revision recorded).

boolean

Example^generated

{
  "repositoryId": "example",
  "revisionId": "example",
  "unchanged": true
}

400

Invalid request

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

message

required

string

Example

{
  "error": {
    "code": "unauthorized"
  }
}

401

Missing, malformed, expired, or revoked token

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

message

required

string

Example

{
  "error": {
    "code": "unauthorized"
  }
}

403

The token lacks the required scope

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

message

required

string

Example

{
  "error": {
    "code": "unauthorized"
  }
}

404

Resource not in this token’s project or repo allowlist

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

message

required

string

Example

{
  "error": {
    "code": "unauthorized"
  }
}

409

A compare-and-set (expectedContent) missed: the guidance changed since it was read. Re-read the current guidance and retry.

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

message

required

string

Example

{
  "error": {
    "code": "unauthorized"
  }
}