Skip to content
Vibase Vibase Docs

Propose a change for review

POST
/api/v1/action-requests

Proposes any proposal-eligible operation with its arguments; nothing changes until a reviewer approves. Needs :request_approval (or write) on the operation’s resource, and the operation’s own validation applies as for a direct call. Write-capable callers may propose too, to ask for review.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
object
operation
required

The proposal-eligible operation to run on approval, for example tasks.update. Each operation’s metadata (x-vault-proposal in OpenAPI) says what proposing it needs.

string
Allowed values: tasks.create tasks.update tasks.delete companies.create companies.update companies.delete contacts.create contacts.update contacts.delete identities.create identities.update identities.delete notes.create notes.update notes.delete tags.create tags.update tags.delete pipelines.create pipelines.update pipelines.delete pipeline_stages.create pipeline_stages.update pipeline_stages.delete deals.create deals.update deals.delete deals.move_stage associations.create associations.delete identities.resolve contacts.merge messages.send
arguments
required

The operation’s flat arguments: its path, query and body fields in one object, exactly as its MCP tool takes them.

object
key
additional properties
reason
required

Why this change is proposed, plain text, for the reviewer.

string
>= 1 characters <= 2000 characters
evidence

Messages and interactions the proposal rests on.

Array<object>
<= 20 items
object
type
required
string
Allowed values: message interaction
id
required
string format: uuid
contact_id

Context: the contact this is about (needs contacts:read).

string format: uuid
thread_id

Context: the thread this is about (needs messages:read).

string format: uuid
interaction_id

Context: the interaction this is about (needs interactions:read); it must belong to thread_id when both are given.

string format: uuid
dedup_key

At most one pending request per key: the same proposer replaces its earlier request, another proposer gets 409 duplicate_action_request.

string
>= 1 characters <= 200 characters
expires_at

When the request stops being approvable; default 7 days, at most 30.

string format: date-time

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Success

object
id
required
string format: uuid
organization_id
required
string format: uuid
operation
required

The registered operation proposed, for example tasks.update.

string
arguments
required

The operation’s flat arguments as proposed (the MCP shape: path, query and body fields in one object). Never changed after creation.

object
key
additional properties
edited_arguments
required

The complete replacement arguments a reviewer approved instead; null unless approved with an edit.

object | null
status
required
string
Allowed values: pending approved rejected withdrawn expired superseded executed failed
reason
required
string
evidence
required
Array<object>
object
type
required
string
Allowed values: message interaction
id
required
string format: uuid
contact_id
required
string | null format: uuid
thread_id
required
string | null format: uuid
interaction_id
required
string | null format: uuid
dedup_key
required
string | null
expires_at
required
string
decided_by
required

The principal (user or agent) that decided it; the system principal for an expiry.

string | null format: uuid
decided_at
required
string | null
decision_reason
required
string | null
superseded_by_id
required
string | null format: uuid
result

What approval did: for an inline operation { events: [{ type, resource_type, resource_id }] }, the events it wrote; for a queued one the execution’s result. Null until executed.

error_code
required
string | null
error_message
required
string | null
executed_at
required
string | null
execution_id

The execution a queued approval created; absent or null until then and for operations that run inline.

string | null format: uuid
created_by
required

The principal that proposed it: the source.

string format: uuid
created_at
required
string
updated_at
required
string