Skip to main content
PUT
Update state

Authorizations

Authorization
string
header
required

API token from cargo-ai login. Send as Authorization: Bearer <token>.

Scopes

openid

OpenID Connect identity.

profile

Name and profile claims.

email

Email address.

offline_access

Refresh token.

Headers

Idempotency-Key
string

Client-generated key that makes this write safe to retry. Reusing the same key with the same request returns the original response instead of creating a second record. Reusing it with a different request returns 422. A concurrent retry while the first request is still running returns 409. Keys expire after 24 hours. Not accepted on multipart file uploads. Optional: a request without one is processed as it always was.

Maximum string length: 255
Example:

"8e03978e-40d5-43e8-bc93-6894a57f9324"

Path Parameters

uuid
string<uuid>
required

State identifier.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Body

application/json

Request body schema.

gitOwner
string

Owner of the repository this project lives in. Refused while the repository is connected.

Required string length: 1 - 255
gitRepo
string

Repository this project lives in. Refused while the repository is connected.

Required string length: 1 - 255
directory
string

Project directory inside the repository, the one holding cargo.json. Refused while the repository is connected.

Maximum string length: 1024
productionBranch
string

Pushes to this branch deploy. Changing it on a connected repository requires the caller to cover the run-as user's permissions.

Required string length: 1 - 255
contents
Contents · object

Deploy state to store.

contentsVersion
integer

Version this write is based on — the one returned by the read. A mismatch means somebody else wrote in between and the request is refused. Required with contents.

Required range: 0 <= x <= 9007199254740991
lockHolderId
string

Identifier of the lock this run holds. Required while another run holds the lock.

Required string length: 1 - 255
snapshotPrevious
boolean

Keep what is being overwritten as this state's rollback point.

connection
Connection · object

Settings of the connection. Changing the run-as user requires the caller to cover its permissions.

meta
Meta · object

Keys to write into the state's meta, each replacing the stored one. A key sent as null is removed, and keys not sent are kept.

endpoint
Endpoint · object | null

Where Cargo asks for the config of the chats this project answers with, and on which triggers, or null to remove it. The state trigger needs a connected repository. Those chats run as the run-as user, so setting it needs permission to run as that user; removing it does not.

Response

Update state

state
object
required