Skip to content

Upload my profile picture (user)

Sets the authenticated user's profile picture, replacing any previous one. Send the file as multipart/form-data in the image field.

The picture is normalized once on upload: its EXIF orientation is applied, metadata (GPS, camera) is removed, it is center-cropped to a square, scaled down to at most 512×512 px (never up), and saved as a high-quality JPEG.

The response holds the new public link, also returned from now on by GET /me as profile_picture_url:

https://cockpit.voxbi.com/avatar/{key} (optional ?size=32…512)

The link needs no token, is cacheable (Cache-Control: public, max-age=86400, ETag), and changes with every upload. Requires a user-owned bearer token.

HTTP: bearerAuth

User bearer token. Default authentication for customer-facing endpoints. Obtain a token by calling POST /login with your credentials, then send it on every subsequent request as Authorization: Bearer <token>. The token inherits the permissions and PBX scope of the authenticated user.

HTTP Authorization Scheme
bearer
Bearer format
Bearer <token>
accept header · string
example: application/json

Request body · required · multipart/form-data

Request schema
image*file
JPG, PNG, WebP or GIF (first frame), at least 128×128 px, up to 10 MB.

Responses

Saved.
Response schema
messagestring
dataobject
profile_picture_urlstring · uri
Authorization Token Missing. This error is returned when the authorization token is missing.
Response schema
errorstring
Error message
example: Authorization Token is missing
The token is not a user token. A PBX API key uses `/users/{user}/profile-picture` (scope `user-profile-pictures`) instead.
Response schema
messagestring
The picture is synced from Microsoft 365 and cannot be changed in Cockpit while the PBX syncs pictures. Change it in Microsoft 365.
Response schema
messagestring
dataobject
profile_picture_urlstring · uri
The file is missing, not an image, too small or too large.
Response schema
messagestring
errorsobject
Free-form object
Too many uploads or removals (10 per minute per caller).
Response schema
messagestring
Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue.
Response schema
messagestring
exceptionstring
Only present in non-production environments.
filestring
Only present in non-production environments.
lineinteger
Only present in non-production environments.
post https://cockpit.voxbi.com/api/v1/me/profile-picture
Base URL
Request sample
curl -X POST 'https://cockpit.voxbi.com/api/v1/me/profile-picture' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -F 'image=@/path/to/image'
const body = new FormData();
body.append('image', fileInput.files[0]); // /path/to/image

const response = await fetch('https://cockpit.voxbi.com/api/v1/me/profile-picture', {
  method: 'POST',
  headers: { Authorization: `Bearer ${YOUR_TOKEN}` },
  body,
});

const data = await response.json();
console.log(data);
import requests

response = requests.post(
    'https://cockpit.voxbi.com/api/v1/me/profile-picture',
    headers={'Authorization': f'Bearer {YOUR_TOKEN}'},
    files={
        'image': open('/path/to/image', 'rb'),
    },
)
response.raise_for_status()
data = response.json()
print(data)
<?php
$ch = curl_init('https://cockpit.voxbi.com/api/v1/me/profile-picture');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer YOUR_TOKEN']);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
    'image' => new CURLFile('/path/to/image'),
]);

$data = json_decode(curl_exec($ch), true);
print_r($data);
Sample request · multipart/form-data
{ … }
"image": "/path/to/image"
}
{ … }
"message": "Profile picture updated.",
"data": { … }
"profile_picture_url": "https://cockpit.voxbi.com/avatar/k3Pq9ZtLm2Xw8nBv7pRa"
}
}
{ … }
"error": "Authorization Token is missing"
}
Cache-Control string
example: private, must-revalidate
Connection string
example: keep-alive
Content-Type string
example: application/json
Vary string
example: Origin
X-RateLimit-Limit integer
Max requests allowed in the current rate-limit window.
example: 60
X-RateLimit-Remaining integer
Requests remaining in the current rate-limit window.
example: 57
{ … }
"message": ""
}
{ … }
"message": "This profile picture is synced from Microsoft 365. Change it in Microsoft 365.",
"data": { … }
"profile_picture_url": "https://cockpit.voxbi.com/avatar/k3Pq9ZtLm2Xw8nBv7pRa"
}
}
{ … }
"message": "The image must be at least 128×128 pixels.",
"errors": { … }
"image": [ … ]
"The image must be at least 128×128 pixels."
]
}
}
{ … }
"message": "Too Many Attempts."
}
{ … }
"message": "Server Error"
}