Update own profile

PATCH

/v1/profile

const url = 'https://example.com/v1/profile';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"user":{"name":"example"},"account":{"name":"example","external_id":"example","country":"example","timezone":"example","phone":"example","limits":{}}}'
};

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

curl --request PATCH \
  --url https://example.com/v1/profile \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "user": { "name": "example" }, "account": { "name": "example", "external_id": "example", "country": "example", "timezone": "example", "phone": "example", "limits": {} } }'

Shallow partial update of the caller’s own user and account. Only top-level groups present in the body are applied. Editing account requires profile:manager; editing account.limits requires limits:account.

Authorizations

bearerAuth

Request Body^required

application/json

Top-level groups are applied only when present. Nested objects overwrite wholesale (no deep merge).

object

user

object

name

string

account

object

name

string

external_id

string

country

string

timezone

string

phone

Digits only, no separators.

string

/^[0-9]*$/

limits

Account-level usage caps aggregated across the account’s agents and communication strategies. Stub for now (empty); populated once reporting/CDR provides the source.

object

Example^generated

{
  "user": {
    "name": "example"
  },
  "account": {
    "name": "example",
    "external_id": "example",
    "country": "example",
    "timezone": "example",
    "phone": "example",
    "limits": {}
  }
}

Responses

200

application/json

object

user

required

object

sid

required

string

account_sid

required

string

email

required

string

name

required

string

roles

required

Array<string>

status

required

string

Allowed values: active inactive

has_password

required

boolean

last_login_at

required

string format: date-time

nullable

account

required

object

sid

required

string

tenant_sid

required

string

tenant_name

required

string

name

required

string

email

required

string

external_id

required

string

country

required

string

timezone

required

string

phone

required

string

status

required

string

Allowed values: active inactive

limits

Account-level usage caps aggregated across the account’s agents and communication strategies. Stub for now (empty); populated once reporting/CDR provides the source.

object

feature_flags

required

Every declared feature flag evaluated for the caller’s account. The set is closed: each flag is always present, and adding one is an API change.

object

global_llm

required

boolean

global_stt

required

boolean

global_tts

required

boolean

Example

{
  "user": {
    "status": "active"
  },
  "account": {
    "status": "active"
  },
  "feature_flags": {
    "global_llm": true,
    "global_stt": false,
    "global_tts": true
  }
}

400

Invalid request body or parameters

application/json

object

error

required

Stable lower_snake_case usecase code (e.g. scenario_not_found)

string

code

required

Registered machine code — generic ERRxxx by status class (ERR001–ERR020 reserved); entity-prefixed codes (SCN1xx) appear only inside validation details; registry in docs/specifications/error-envelope-design.md, append-only, never renumbered

string

message

required

string

data

Structured details, present only where there is structure to carry: validation failures (topic validation, per-entity errors) and delete conflicts (topic conflict, referencing agents)

object

topic

string

errors

Validation errors keyed by entity

object

scenario

Array<object>

object

code

SCN1xx constructor validation code

string

message

string

summary

string

tree_id

string

node_id

string

output_type

string

duplicate_tree_index

string

duplicate_node_index

string

property

string

invalid_value

string

agents

Ids of the agents referencing the resource a delete was rejected for; first 20 — message carries the total count

Array<string>

Example^generated

{
  "error": "example",
  "code": "example",
  "message": "example",
  "data": {
    "topic": "example",
    "errors": {
      "scenario": [
        {
          "code": "example",
          "message": "example",
          "summary": "example",
          "tree_id": "example",
          "node_id": "example",
          "output_type": "example",
          "duplicate_tree_index": "example",
          "duplicate_node_index": "example",
          "property": "example",
          "invalid_value": "example"
        }
      ]
    },
    "agents": [
      "example"
    ]
  }
}

401

Missing or invalid credentials

application/json

object

error

required

Stable lower_snake_case usecase code (e.g. scenario_not_found)

string

code

required

string

message

required

string

data

Structured details, present only where there is structure to carry: validation failures (topic validation, per-entity errors) and delete conflicts (topic conflict, referencing agents)

object

topic

string

errors

Validation errors keyed by entity

object

scenario

Array<object>

object

code

SCN1xx constructor validation code

string

message

string

summary

string

tree_id

string

node_id

string

output_type

string

duplicate_tree_index

string

duplicate_node_index

string

property

string

invalid_value

string

agents

Ids of the agents referencing the resource a delete was rejected for; first 20 — message carries the total count

Array<string>

Example^generated

{
  "error": "example",
  "code": "example",
  "message": "example",
  "data": {
    "topic": "example",
    "errors": {
      "scenario": [
        {
          "code": "example",
          "message": "example",
          "summary": "example",
          "tree_id": "example",
          "node_id": "example",
          "output_type": "example",
          "duplicate_tree_index": "example",
          "duplicate_node_index": "example",
          "property": "example",
          "invalid_value": "example"
        }
      ]
    },
    "agents": [
      "example"
    ]
  }
}

403

Caller has no access

application/json

object

error

required

Stable lower_snake_case usecase code (e.g. scenario_not_found)

string

code

required

string

message

required

string

data

Structured details, present only where there is structure to carry: validation failures (topic validation, per-entity errors) and delete conflicts (topic conflict, referencing agents)

object

topic

string

errors

Validation errors keyed by entity

object

scenario

Array<object>

object

code

SCN1xx constructor validation code

string

message

string

summary

string

tree_id

string

node_id

string

output_type

string

duplicate_tree_index

string

duplicate_node_index

string

property

string

invalid_value

string

agents

Ids of the agents referencing the resource a delete was rejected for; first 20 — message carries the total count

Array<string>

Example^generated

{
  "error": "example",
  "code": "example",
  "message": "example",
  "data": {
    "topic": "example",
    "errors": {
      "scenario": [
        {
          "code": "example",
          "message": "example",
          "summary": "example",
          "tree_id": "example",
          "node_id": "example",
          "output_type": "example",
          "duplicate_tree_index": "example",
          "duplicate_node_index": "example",
          "property": "example",
          "invalid_value": "example"
        }
      ]
    },
    "agents": [
      "example"
    ]
  }
}

422

Semantic validation failure

application/json

object

error

required

Stable lower_snake_case usecase code (e.g. scenario_not_found)

string

code

required

string

message

required

string

data

Structured details, present only where there is structure to carry: validation failures (topic validation, per-entity errors) and delete conflicts (topic conflict, referencing agents)

object

topic

string

errors

Validation errors keyed by entity

object

scenario

Array<object>

object

code

SCN1xx constructor validation code

string

message

string

summary

string

tree_id

string

node_id

string

output_type

string

duplicate_tree_index

string

duplicate_node_index

string

property

string

invalid_value

string

agents

Ids of the agents referencing the resource a delete was rejected for; first 20 — message carries the total count

Array<string>

Example^generated

{
  "error": "example",
  "code": "example",
  "message": "example",
  "data": {
    "topic": "example",
    "errors": {
      "scenario": [
        {
          "code": "example",
          "message": "example",
          "summary": "example",
          "tree_id": "example",
          "node_id": "example",
          "output_type": "example",
          "duplicate_tree_index": "example",
          "duplicate_node_index": "example",
          "property": "example",
          "invalid_value": "example"
        }
      ]
    },
    "agents": [
      "example"
    ]
  }
}

Update own profile

Authorizations

Request Bodyrequired

Examplegenerated

Responses

200

Example

400

Examplegenerated

401

Examplegenerated

403

Examplegenerated

422

Examplegenerated

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated