Skip to content

Update Profile API

The Update Profile API lets a developer update a profile by sending a PATCH request to /v1/profiles/{id}. Use this endpoint when the task is to change a profile's name, its description, or both, while keeping the same Profile ID in the path.

Update Profile API contract summary

Update a profile by sending PATCH to {{API_BASE_URL}}/v1/profiles/{id}. The request uses the x-access-key header for authorization, a required string id path parameter described as Profile ID, and an application/json request body. The two body fields are optional: name is a string with length from 1 to 200 characters, and description is a string or null with length up to 1000 characters. Before sending, check that the id in the path is the intended Profile ID, that name is not empty when supplied, and that description respects the 1000-character limit when it is a string. The worked request example below shows the origin-modular form of the call; refer to its title when reviewing the sample rather than relying on prose alone.

Authorization

Send the access token in the x-access-key header. The documented header name is x-access-key and the value placeholder is <token>. If a call fails for authorization reasons, verify that the header name is spelled exactly as x-access-key, that the token value is present, and that no extra whitespace or alternate header name was substituted. This page does not add token issuance, rotation, or storage guidance because those details are not part of the supplied contract for this endpoint.

Path parameters

The path contains one required parameter, id, typed as string and described as Profile ID. Replace the {id} segment with the actual Profile ID for the profile being updated. A common failure is sending a display name or another identifier in place of the Profile ID; compare the path value against the id returned in a profile object before retrying. The field map below separates this path parameter from header, request-body, and response fields so each value can be checked in the right place.

Request body

The request body is application/json and contains only the optional name and description fields in the documented contract. Supply name to change the profile name, supply description to change the profile description, or supply both in the same request. Keep name between 1 and 200 characters inclusive, and keep a string description at or below 1000 characters. Because description is typed as string | null, null is an allowed value in the schema; do not assume additional clearing behavior beyond that type. The request-body field map below records requiredness, type, and length constraints for each field.

200 application/json

A successful update returns 200 with an application/json body containing success set to true and a profile object. The profile object includes id, name, description, integrationCount, createdAt, and updatedAt. Treat integrationCount as the count of integrations bound to the profile in the returned object, and treat createdAt and updatedAt as date-time strings. After a 200 response, read the returned profile object as the authoritative result of the update and compare its id with the Profile ID used in the request path. The success response example below preserves the exact field names and types from the contract.

400 application/json

A 400 response returns an application/json body with a required error string. When this status is returned, inspect the error value, then recheck the request body against the field map: confirm that name, when present, is a string of 1 to 200 characters and that description, when present, is a string of up to 1000 characters or null. Also confirm that the request was sent as application/json and that the path still contains a string Profile ID. Do not change the endpoint path or method while correcting the payload.

404 application/json

A 404 response returns an application/json body with a required error string. When this status is returned, inspect the error value and verify that the id in /v1/profiles/{id} is the correct Profile ID for an existing profile. A mismatch between the path id and the profile object id in a later successful response is a sign that the wrong identifier was used. Correct the Profile ID and retry with the same PATCH method, x-access-key header, and request-body rules.

Failure matrix and caller checks

Use the failure matrix below as a caller checklist after each call. For 200, confirm success is true and store the returned profile fields, including integrationCount, createdAt, and updatedAt. For 400, read the error string and validate name and description against their length and type rules before retrying. For 404, read the error string and verify the Profile ID in the path before retrying. Keep the method as PATCH and the path as /v1/profiles/{id} in every retry so the request stays within the documented contract.

Update Profile API field map
LocationFieldTypeRequiredConstraints / description
Headerx-access-keystring (<token>)Required for authorizationAuthorization header; value placeholder is <token>
PathidstringRequiredProfile ID
Request bodynamestringOptional1 <= length <= 200
Request bodydescriptionstring | nullOptionallength <= 1000 when a string
Response body (200)successbooleanRequiredtrue in the documented success example
Response body (200)profileobjectRequiredContains the updated profile object
Response body (200)profile.idstringRequiredProfile ID
Response body (200)profile.namestringRequiredUpdated profile name
Response body (200)profile.descriptionstring | nullRequiredUpdated profile description or null
Response body (200)profile.integrationCountintegerRequired0 <= value
Response body (200)profile.createdAtstringRequireddate-time format
Response body (200)profile.updatedAtstringRequireddate-time format
Response body (400/404)errorstringRequiredError message string

Exact documented contract; illustrative parity draft.

Update Profile API failure matrix
StatusResponse shapeCaller check and action
200 application/jsonsuccess: boolean (true), profile: object with id, name, description, integrationCount, createdAt, updatedAtConfirm the returned profile.id matches the Profile ID in the path; store name, description, integrationCount, createdAt, and updatedAt from the response.
400 application/jsonerror: stringRead error; recheck name length (1-200), description type and length (string | null, <=1000), JSON content type, and the string id path parameter.
404 application/jsonerror: stringRead error; verify the id in /v1/profiles/{id} is the correct Profile ID, then retry with PATCH and the x-access-key header.

Trigger conditions beyond status and shape are not supplied; actions are limited to documented checks.

Update Profile API request example
curl -X PATCH "{{API_BASE_URL}}/v1/profiles/{id}" \
  -H "Content-Type: application/json" \
  -H "x-access-key: <token>" \
  -d '{
    "name": "Updated profile name",
    "description": "Example post details."
  }'
200 application/json success response
{
  "success": true,
  "profile": {
    "id": "string",
    "name": "string",
    "description": "string",
    "integrationCount": 0,
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
400 and 404 application/json error response
{
  "error": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
id#1idstring__0YesProfile ID
body#2bodyobject__0Yes
body#2body.namestring__1Nokind: schemaLength; value: 1 <= length <= 200
body#2body.descriptionstring | null__2Nokind: schemaLength; value: length <= 1000
body#2body.description[variant1]string__2_type:stringkind: schemaLength; value: length <= 1000
body#2body.description[variant2]null__2_type:nullkind: ; value: length <= 1000
response#3responseobject__0
response#3response.successboolean__1Yes
response#3response.profileobject__2Yes
response#3response.profile.idstring__3Yes
response#3response.profile.namestring__4Yes
response#3response.profile.descriptionstring | null__5Yes
response#3response.profile.description[variant1]string__5_type:string
response#3response.profile.description[variant2]null__5_type:null
response#3response.profile.integrationCountinteger__6YesNumber of active integrations bound to this profilekind: schemaRange; value: 0 <= value
response#3response.profile.createdAtstring__7Yeskind: schemaFormat; value: date-time
response#3response.profile.updatedAtstring__8Yeskind: schemaFormat; value: date-time
response#4responseobject__0
response#4response.errorstring__1Yes