Acknowledge, resolve, or assign a caller request

PATCH

/v1/caller-requests/{request_id}

curl --request PATCH \
  --url https://api.vocapable.com/v1/caller-requests/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "version": 1, "state": "acknowledged", "assignee_user_id": "example", "note": "example" }'

One optimistic-concurrency move: the caller names the version they read.

A version mismatch and an illegal transition are both 409s with distinct codes, so the portal can tell “refresh and retry” from “someone already resolved this”. ticket.resolved is appended in this same transaction (append_once on the request id - resolved is terminal, so once is all there ever is).

Authorizations

• HTTPBearer

Parameters

Path Parameters

request_id

required

Request Id

string

Request Body^required

Media typeapplication/json

CallerRequestUpdateRequest

PATCH /v1/caller-requests/{id} - acknowledge, resolve, or (re)assign.

version is mandatory: the caller names the revision they read, and a mismatch is a 409 rather than a silent last-write-wins. state may only move forward - open → acknowledged → resolved, or open → resolved directly; resolved is terminal (no reopen in v1, ADR-0037 records the deferral). assignee_user_id uses PATCH presence semantics: absent means no assignment edit, an explicit null clears it.

object

version

required

Version

integer

>= 1

state

Any of:

string

string

Allowed values: acknowledged resolved

null

null

assignee_user_id

Any of:

string

string

>= 1 characters <= 128 characters

null

null

note

Any of:

string

string

>= 1 characters <= 1000 characters

null

null

Responses

200

Successful Response

Media typeapplication/json

CallerRequestResource

The single-request read, with its full event trail embedded oldest-first.

object

id

required

Id

string

kind

required

Kind

string

Allowed values: message support_ticket

state

required

State

string

Allowed values: open acknowledged resolved

severity

Any of:

string

string

Allowed values: critical high normal low

null

null

contact_id

Any of:

string

string

null

null

call_id

Any of:

string

string

null

null

agent_version_id

Any of:

string

string

null

null

phone_number_id

Any of:

string

string

null

null

caller_name

Any of:

string

string

null

null

subject

Any of:

string

string

null

null

body

required

Body

string

assignee_user_id

Any of:

string

string

null

null

acknowledged_by_ref

Any of:

string

string

null

null

acknowledged_at

Any of:

string

string format: date-time

null

null

resolved_by_ref

Any of:

string

string

null

null

resolved_at

Any of:

string

string format: date-time

null

null

version

required

Version

integer

created_at

required

Created At

string format: date-time

updated_at

required

Updated At

string format: date-time

events

Events

Array<object>

CallerRequestEventOut

One append-only transition on a request’s trail.

object

id

required

Id

string

action

required

Action

string

Allowed values: opened acknowledged resolved assigned

actor_ref

required

Actor Ref

string

note

Any of:

string

string

null

null

created_at

required

Created At

string format: date-time

Example

{
  "kind": "message",
  "state": "open",
  "severity": "critical",
  "events": [
    {
      "action": "opened"
    }
  ]
}

422

Validation Error

Media typeapplication/json

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

input

Input

ctx

Context

object

Example^generated

{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}