Change a process

POST

/memory/processes/{processId}/versions

const url = 'https://api.asklucy.eu/v1/memory/processes/example/versions';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"title":"example","when":"example","body":"example","reads":["example"],"writes":["example"],"applies_to":["example"],"rationale":"example","base_version_id":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.asklucy.eu/v1/memory/processes/example/versions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "title": "example", "when": "example", "body": "example", "reads": [ "example" ], "writes": [ "example" ], "applies_to": [ "example" ], "rationale": "example", "base_version_id": "example" }'

A new version, from the current one (base_version_id). In your own scope it is accepted and becomes current; for a group or the organization it is proposed. If base_version_id is no longer the current version, someone changed the process meanwhile: 409 …/errors/proposal-stale.

Authorizations

zitadel

Parameters

Path Parameters

processId

required

string

/^proc_[A-Za-z0-9]+$/

Header Parameters

Idempotency-Key

string

<= 255 characters

Any unique string (a UUID works). Retries with the same key return the first result.

Request Body^required

application/json

object

title

required

string

>= 1 characters <= 200 characters

when

required

string

>= 1 characters <= 1000 characters

body

required

The steps, in Markdown.

string

>= 1 characters <= 8000 characters

reads

Array<string>

<= 20 items

writes

Array<string>

<= 20 items

applies_to

The entities it is about (IDs). They must be shared at least as widely as the process.

Array<string>

<= 20 items

rationale

string | null

<= 2000 characters

base_version_id

required

The current version you started from; null when the process has none yet.

string | null

Example ^generated

{
  "title": "example",
  "when": "example",
  "body": "example",
  "reads": [
    "example"
  ],
  "writes": [
    "example"
  ],
  "applies_to": [
    "example"
  ],
  "rationale": "example",
  "base_version_id": "example"
}

Responses

201

Created

application/json

object

required

string

process_id

required

string

version

required

1, 2, … in order of creation, proposals included.

integer

>= 1

state

required

proposed: waiting for an admin.
accepted: the current version.
superseded: was current, replaced by a later version.
rejected: an admin turned the proposal down.
withdrawn: its author took it back or undid it.

string

Allowed values: proposed accepted rejected superseded withdrawn

title

required

string

when

required

When to use it (the requests or situations it is for).

string

body

required

The steps, in Markdown.

string

reads

required

Types of entities and relations it reads.

Array<string>

writes

required

Types of entities and relations it writes.

Array<string>

applies_to

required

The entities it is about (IDs).

Array<string>

rationale

required

Why it was written or changed; empty when not given.

string

base_version_id

required

The version it was written from; null for a first version.

string | null

author

required

A person, or Lucy working for that person. The person is null once their memory was erased.

object

kind

required

string

Allowed values: person lucy

user_id

required

string | null

name

required

The person’s name.

string | null

source_conversation_id

required

The conversation Lucy wrote it in; given only to its author.

string | null

flags

required

untrusted_input: Lucy wrote it after reading a file or a tool’s output, which may have steered her. Review it with care.

Array<string>

Allowed values: untrusted_input

decided_by

required

One of:

object
null

object

required

Zitadel user ID.

string

name

required

string

email

string | null format: email

kind

service is a customer system’s Zitadel service user; agent is a service agent (its ID is the agt_ ID), the author of its runs’ messages.

string

Allowed values: person service agent

decided_at

required

string | null format: date-time

decision_note

required

string | null

created_at

required

string format: date-time

Example

{
  "id": "prv_7Hc2Lw",
  "state": "proposed",
  "title": "Answer a custody-fee question",
  "when": "Someone asks why custody fees changed, or to check a custody invoice.",
  "reads": [
    "company"
  ],
  "writes": [
    "invoice"
  ],
  "applies_to": [
    "ent_5Tq9Bm"
  ],
  "author": {
    "kind": "person"
  },
  "flags": [
    "untrusted_input"
  ],
  "decided_by": {
    "kind": "person"
  }
}

400

The request is invalid; errors lists what’s wrong.

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.

401

Missing, expired or invalid token.

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.

403

The token lacks the role this needs (…/errors/forbidden), or memory is off for the organization or, in your own scope, for you (…/errors/memory-disabled; getMemory says which).

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.

404

No such object in your organization.

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.

409

The version isn’t in a state that allows this, e.g. the proposal was already decided (…/errors/version-state), or its base is no longer the process’s current version (…/errors/proposal-stale).

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.

Change a process

Authorizations

Parameters

Path Parameters

Header Parameters

Request Bodyrequired

Example generated

Responses

201

Example

400

Example

Headers

401

Example

Headers

403

Example

Headers

404

Example

Headers

409

Example

Headers

Request Body^required

Example ^generated