Update a user profile

⚠️
Preview — this feature is being built; the design below is the spec.
PATCH https://app.syntic.ai/v1/user_profiles/{profile_id}

Change a profile. attributes are merged key by key and a key set to null is removed. Running sessions see the new values from their next turn.

For how this fits into a full workflow, see User profiles.

Headers

HeaderRequiredValue
AuthorizationYesBearer <key>: a private inference key (sk_live_...). See Authentication.
syntic-betaYes, while in previewagents-2026-11-01. Without it the call fails with 400 beta_required. See Versioning.
Content-TypeYesapplication/json

Path parameters

ParameterTypeDescription
profile_idstringThe profile id (uprof_...), or ext: followed by your external_id.

Body parameters

ParameterTypeRequiredNotes
display_namestringNoUp to 120 characters.
localestringNoBCP 47, for example de-DE.
timezonestringNoIANA zone, for example Asia/Dubai.
attributesobjectNoUp to 50 keys; keys up to 64 characters, string values up to 512.
memory_scopestringNoDefault user:<external_id>.

Response

200 OK, Content-Type: application/json

{
  "id": "uprof_01JCF5H7K9M1P3R5T7V9",
  "type": "user_profile",
  "external_id": "cust-4821",
  "display_name": "Dana Lee",
  "locale": "fr-FR",
  "timezone": "Europe/London",
  "attributes": {
    "plan": "platinum"
  },
  "memory_scope": "user:cust-4821",
  "session_count": 17,
  "created_at": "2026-10-02T09:00:00Z",
  "updated_at": "2026-11-05T10:00:00Z"
}
FieldTypeDescription
idstringStarts with uprof_.
external_idstringYour own id for the person; unique within the workspace.
localestringBCP 47 tag. The agent is told to answer in this language unless the user writes in another.
timezonestringIANA zone. Used for dates in the agent’s context and for deployment schedules that run per user.
attributesobjectUp to 50 keys, string, number or boolean values. Visible to the agent as facts about the user.
memory_scopestringThe scope used when agents read or write memories about this person.
session_countintegerSessions started with this profile.

Examples

curl -sS -X PATCH "https://app.syntic.ai/v1/user_profiles/uprof_01JCF5H7K9M1P3R5T7V9" \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "syntic-beta: agents-2026-11-01" \
  -H "Content-Type: application/json" \
  -d '{
      "locale": "fr-FR",
      "attributes": {
        "plan": "platinum",
        "region": null
      }
    }'

Errors

Errors use the error envelope and carry a request_id. Codes specific to this operation:

StatustypecodeWhen
400invalid_request_errorbeta_requiredThe syntic-beta header is missing.
404not_found_erroruser_profile_not_foundNo profile with this id or external id in the workspace.
401authentication_errorinvalid_api_keyThe key is missing, unknown, revoked or expired.
429rate_limit_errorrate_limitedToo many requests; wait for Retry-After. See Rate-limit headers.
Was this page helpful?