> For the complete documentation index, see [llms.txt](https://docs.hesh.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hesh.app/manuals/public-api/users.md).
# Users
## List users
> \
> Returns active users in the tenant, paginated. Excludes hard-deleted and soft-deleted users. Each entry carries \`id\`, \`first\_name\`, \`last\_name\`, a convenience \`full\_name\` (\`first\_name + " " + last\_name\`), and \`email\`.\
> \
> \### Query\
> \
> \- \`search\` — optional case-insensitive substring match on the concatenated full name (\`CONCAT(first\_name, ' ', last\_name)\`).\
> \- \`page\` / \`limit\` — defaults \`page = 1\`, \`limit = 25\`, max \`limit = 100\`.
```json
{"openapi":"3.0.0","info":{"title":"Public API","version":"1.0"},"tags":[{"name":"Users"}],"servers":[{"url":"https://api-stage.hesh.tech"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"PublicUsersPageDto":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicUserListItemDto"}},"meta":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","meta"]},"PublicUserListItemDto":{"type":"object","properties":{"id":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"full_name":{"type":"string","description":"Convenience concatenation of `first_name` + \" \" + `last_name`."},"email":{"type":"string"}},"required":["id","first_name","last_name","full_name","email"]},"PaginationMetadata":{"type":"object","properties":{"total":{"type":"number","description":"Total number of items"},"lastPage":{"type":"number","description":"Last page number"},"currentPage":{"type":"number","description":"Current page number"},"perPage":{"type":"number","description":"Items per page"},"prev":{"type":"number","description":"Previous page number","nullable":true},"next":{"type":"number","description":"Next page number","nullable":true}},"required":["total","lastPage","currentPage","perPage","prev","next"]}}},"paths":{"/api/v1/public/users":{"get":{"description":"\nReturns active users in the tenant, paginated. Excludes hard-deleted and soft-deleted users. Each entry carries `id`, `first_name`, `last_name`, a convenience `full_name` (`first_name + \" \" + last_name`), and `email`.\n\n### Query\n\n- `search` — optional case-insensitive substring match on the concatenated full name (`CONCAT(first_name, ' ', last_name)`).\n- `page` / `limit` — defaults `page = 1`, `limit = 25`, max `limit = 100`.\n","operationId":"PublicUsersController_listUsers_v1","parameters":[{"name":"search","required":false,"in":"query","description":"Case-insensitive substring match on `first_name last_name`.","schema":{"maxLength":100,"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":25,"type":"number"}},{"name":"x-tenant-id","in":"header","description":"Tenant id (uuid v4)","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicUsersPageDto"}}}},"429":{"description":"Returned when the rate limit is exceeded","headers":{"X-RateLimit-Limit":{"description":"Maximum number of allowed requests during the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining number of requests before throttling occurs","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Number of seconds until the rate limit window resets","schema":{"type":"integer"}}}}},"summary":"List users","tags":["Users"]}}}}
```
## Create a single user
> Creates a new user.
```json
{"openapi":"3.0.0","info":{"title":"Public API","version":"1.0"},"tags":[{"name":"Users"}],"servers":[{"url":"https://api-stage.hesh.tech"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"PublicUserRequestDto":{"type":"object","properties":{"external_user_id":{"type":"string","description":"External identifier for the user (e.g., UUID)"},"email":{"type":"string","format":"email","description":"The user's email address"},"first_name":{"type":"string","minLength":1,"maxLength":10,"description":"The user's first name"},"last_name":{"type":"string","minLength":1,"maxLength":100,"description":"The user's last name"},"phone":{"type":"string","maxLength":50,"description":"The user's phone number"},"status":{"type":"string","description":"Current status of the user account","enum":["Active","Inactive","Pending"],"default":"Active"}},"required":["external_user_id","email","first_name","last_name"]},"PublicUserResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique internal identifier of the user"},"email":{"type":"string","format":"email","description":"The user's email address"},"avatar_id":{"type":"string","nullable":true,"description":"URL to the user's avatar image"},"first_name":{"type":"string","description":"The user's first name"},"last_name":{"type":"string","description":"The user's last name"},"external_user_id":{"type":"string","nullable":true,"description":"External identifier for the user assigned by third-party system"},"full_name":{"type":"string","description":"The user's full name (first name + last name)"},"phone":{"type":"string","nullable":true,"description":"The user's phone number"},"status":{"type":"string","description":"Current status of the user account","enum":["Active","Inactive","Pending"]},"created_at":{"format":"date-time","type":"string","description":"Timestamp when the user was created"},"userVacations":{"description":"User active vacation / day-off / sick-leave periods","type":"array","items":{"$ref":"#/components/schemas/PublicUserActiveVacationDto"}}},"required":["id","email","avatar_id","first_name","last_name","external_user_id","created_at"]},"PublicUserActiveVacationDto":{"type":"object","properties":{"start_at":{"type":"string","format":"date-time"},"end_at":{"type":"string","format":"date-time"},"type":{"allOf":[{"$ref":"#/components/schemas/UserAbsenceType"}]}},"required":["start_at","end_at","type"]},"UserAbsenceType":{"type":"string","enum":["day_off","sick_leave"]}}},"paths":{"/api/v1/public/users":{"post":{"description":"Creates a new user.","operationId":"PublicUsersController_publicCreate_v1","parameters":[{"name":"x-tenant-id","in":"header","description":"Tenant id (uuid v4)","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicUserRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicUserResponseDto"}}}},"429":{"description":"Returned when the rate limit is exceeded","headers":{"X-RateLimit-Limit":{"description":"Maximum number of allowed requests during the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining number of requests before throttling occurs","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Number of seconds until the rate limit window resets","schema":{"type":"integer"}}}}},"summary":"Create a single user","tags":["Users"]}}}}
```
## Update a single user
> Updates an existing user matched by external\_user\_id. All fields except external\_user\_id are optional — only provided fields are updated.
```json
{"openapi":"3.0.0","info":{"title":"Public API","version":"1.0"},"tags":[{"name":"Users"}],"servers":[{"url":"https://api-stage.hesh.tech"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"UpdatePublicUserRequestDto":{"type":"object","properties":{"external_user_id":{"type":"string","description":"External identifier for the user (used to match the user)"},"email":{"type":"string","format":"email","description":"The user's email address"},"first_name":{"type":"string","minLength":1,"maxLength":100,"description":"The user's first name"},"last_name":{"type":"string","minLength":1,"maxLength":100,"description":"The user's last name"},"phone":{"type":"string","maxLength":50,"description":"The user's phone number"}},"required":["external_user_id"]},"PublicUserResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique internal identifier of the user"},"email":{"type":"string","format":"email","description":"The user's email address"},"avatar_id":{"type":"string","nullable":true,"description":"URL to the user's avatar image"},"first_name":{"type":"string","description":"The user's first name"},"last_name":{"type":"string","description":"The user's last name"},"external_user_id":{"type":"string","nullable":true,"description":"External identifier for the user assigned by third-party system"},"full_name":{"type":"string","description":"The user's full name (first name + last name)"},"phone":{"type":"string","nullable":true,"description":"The user's phone number"},"status":{"type":"string","description":"Current status of the user account","enum":["Active","Inactive","Pending"]},"created_at":{"format":"date-time","type":"string","description":"Timestamp when the user was created"},"userVacations":{"description":"User active vacation / day-off / sick-leave periods","type":"array","items":{"$ref":"#/components/schemas/PublicUserActiveVacationDto"}}},"required":["id","email","avatar_id","first_name","last_name","external_user_id","created_at"]},"PublicUserActiveVacationDto":{"type":"object","properties":{"start_at":{"type":"string","format":"date-time"},"end_at":{"type":"string","format":"date-time"},"type":{"allOf":[{"$ref":"#/components/schemas/UserAbsenceType"}]}},"required":["start_at","end_at","type"]},"UserAbsenceType":{"type":"string","enum":["day_off","sick_leave"]}}},"paths":{"/api/v1/public/users":{"put":{"description":"Updates an existing user matched by external_user_id. All fields except external_user_id are optional — only provided fields are updated.","operationId":"PublicUsersController_updateUser_v1","parameters":[{"name":"x-tenant-id","in":"header","description":"Tenant id (uuid v4)","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePublicUserRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicUserResponseDto"}}}},"429":{"description":"Returned when the rate limit is exceeded","headers":{"X-RateLimit-Limit":{"description":"Maximum number of allowed requests during the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining number of requests before throttling occurs","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Number of seconds until the rate limit window resets","schema":{"type":"integer"}}}}},"summary":"Update a single user","tags":["Users"]}}}}
```
## Create users in batch
> Creates multiple users in a single request. Skips users that already exist (matched by email or phone).
```json
{"openapi":"3.0.0","info":{"title":"Public API","version":"1.0"},"tags":[{"name":"Users"}],"servers":[{"url":"https://api-stage.hesh.tech"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"UsersExchangeDto":{"type":"object","properties":{"users":{"description":"An array containing user objects with the following fields: external_user_id, email, first_name, last_name, and phone","type":"array","items":{"type":"string"}}},"required":["users"]},"PublicUserResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique internal identifier of the user"},"email":{"type":"string","format":"email","description":"The user's email address"},"avatar_id":{"type":"string","nullable":true,"description":"URL to the user's avatar image"},"first_name":{"type":"string","description":"The user's first name"},"last_name":{"type":"string","description":"The user's last name"},"external_user_id":{"type":"string","nullable":true,"description":"External identifier for the user assigned by third-party system"},"full_name":{"type":"string","description":"The user's full name (first name + last name)"},"phone":{"type":"string","nullable":true,"description":"The user's phone number"},"status":{"type":"string","description":"Current status of the user account","enum":["Active","Inactive","Pending"]},"created_at":{"format":"date-time","type":"string","description":"Timestamp when the user was created"},"userVacations":{"description":"User active vacation / day-off / sick-leave periods","type":"array","items":{"$ref":"#/components/schemas/PublicUserActiveVacationDto"}}},"required":["id","email","avatar_id","first_name","last_name","external_user_id","created_at"]},"PublicUserActiveVacationDto":{"type":"object","properties":{"start_at":{"type":"string","format":"date-time"},"end_at":{"type":"string","format":"date-time"},"type":{"allOf":[{"$ref":"#/components/schemas/UserAbsenceType"}]}},"required":["start_at","end_at","type"]},"UserAbsenceType":{"type":"string","enum":["day_off","sick_leave"]}}},"paths":{"/api/v1/public/users/batch":{"post":{"description":"Creates multiple users in a single request. Skips users that already exist (matched by email or phone).","operationId":"PublicUsersController_createBatch_v1","parameters":[{"name":"x-tenant-id","in":"header","description":"Tenant id (uuid v4)","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsersExchangeDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicUserResponseDto"}}}}},"429":{"description":"Returned when the rate limit is exceeded","headers":{"X-RateLimit-Limit":{"description":"Maximum number of allowed requests during the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining number of requests before throttling occurs","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Number of seconds until the rate limit window resets","schema":{"type":"integer"}}}}},"summary":"Create users in batch","tags":["Users"]}}}}
```
## Disable a user by external\_user\_id
> Sets the user status to Inactive.
```json
{"openapi":"3.0.0","info":{"title":"Public API","version":"1.0"},"tags":[{"name":"Users"}],"servers":[{"url":"https://api-stage.hesh.tech"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"DisableUserByExternalIdDto":{"type":"object","properties":{"external_user_id":{"type":"string","description":"External identifier of the user to disable"}},"required":["external_user_id"]},"MessageDto":{"type":"object","properties":{"message":{"type":"string","description":"Message returned from API confirming the operation"}},"required":["message"]}}},"paths":{"/api/v1/public/users/disable":{"patch":{"description":"Sets the user status to Inactive.","operationId":"PublicUsersController_disableUser_v1","parameters":[{"name":"x-tenant-id","in":"header","description":"Tenant id (uuid v4)","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisableUserByExternalIdDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDto"}}}},"429":{"description":"Returned when the rate limit is exceeded","headers":{"X-RateLimit-Limit":{"description":"Maximum number of allowed requests during the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining number of requests before throttling occurs","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Number of seconds until the rate limit window resets","schema":{"type":"integer"}}}}},"summary":"Disable a user by external_user_id","tags":["Users"]}}}}
```
## Set a user avatar from a url
> Matches the user by external\_user\_id, then downloads the image at \`url\` and sets it as the user's avatar. Downloading happens asynchronously in the background — a 200 response means the update was scheduled, not that it has completed yet.
```json
{"openapi":"3.0.0","info":{"title":"Public API","version":"1.0"},"tags":[{"name":"Users"}],"servers":[{"url":"https://api-stage.hesh.tech"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"PublicSetUserAvatarDto":{"type":"object","properties":{"external_user_id":{"type":"string","description":"External identifier of the user whose avatar is being set"},"url":{"type":"string","description":"Url of the avatar image to download"}},"required":["external_user_id","url"]},"MessageDto":{"type":"object","properties":{"message":{"type":"string","description":"Message returned from API confirming the operation"}},"required":["message"]}}},"paths":{"/api/v1/public/users/avatar":{"post":{"description":"Matches the user by external_user_id, then downloads the image at `url` and sets it as the user's avatar. Downloading happens asynchronously in the background — a 200 response means the update was scheduled, not that it has completed yet.","operationId":"PublicUsersController_setAvatar_v1","parameters":[{"name":"x-tenant-id","in":"header","description":"Tenant id (uuid v4)","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicSetUserAvatarDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDto"}}}},"429":{"description":"Returned when the rate limit is exceeded","headers":{"X-RateLimit-Limit":{"description":"Maximum number of allowed requests during the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining number of requests before throttling occurs","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Number of seconds until the rate limit window resets","schema":{"type":"integer"}}}}},"summary":"Set a user avatar from a url","tags":["Users"]}}}}
```
## Remove a user avatar
> Matches the user by external\_user\_id and clears their avatar. Idempotent — if the user has no avatar set, this is a no-op. The underlying file is deleted from storage only if nothing else references it.
```json
{"openapi":"3.0.0","info":{"title":"Public API","version":"1.0"},"tags":[{"name":"Users"}],"servers":[{"url":"https://api-stage.hesh.tech"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"DeleteUserAvatarDto":{"type":"object","properties":{"external_user_id":{"type":"string","description":"External identifier of the user whose avatar is being removed"}},"required":["external_user_id"]},"MessageDto":{"type":"object","properties":{"message":{"type":"string","description":"Message returned from API confirming the operation"}},"required":["message"]}}},"paths":{"/api/v1/public/users/avatar":{"delete":{"description":"Matches the user by external_user_id and clears their avatar. Idempotent — if the user has no avatar set, this is a no-op. The underlying file is deleted from storage only if nothing else references it.","operationId":"PublicUsersController_deleteAvatar_v1","parameters":[{"name":"x-tenant-id","in":"header","description":"Tenant id (uuid v4)","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteUserAvatarDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDto"}}}},"429":{"description":"Returned when the rate limit is exceeded","headers":{"X-RateLimit-Limit":{"description":"Maximum number of allowed requests during the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining number of requests before throttling occurs","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Number of seconds until the rate limit window resets","schema":{"type":"integer"}}}}},"summary":"Remove a user avatar","tags":["Users"]}}}}
```
## Bulk-sync user avatars from a list of urls, with a report
> \
> Takes a list of \`{ external\_user\_id, avatar\_url }\` rows (e.g. from a one-off import file) and, for each one, downloads the image and sets it as that user's avatar — synchronously, so the outcome of every row is in the response.\
> \
> A row is skipped (never overwrites anything) when:\
> \- \`user\_not\_found\` — no user in Hesh has this \`external\_user\_id\`.\
> \- \`duplicate\_external\_user\_id\` — more than one Hesh user has this \`external\_user\_id\`; \`details\` lists the matched internal user ids for manual review.\
> \- \`user\_inactive\` — the matched user's status is not Active.\
> \- \`avatar\_already\_set\` — the user already has an avatar; existing avatars are never replaced.\
> \- \`url\_unreachable\` — the url could not be downloaded (unreachable, too large, or not an image); \`details\` carries the error.\
> \
> Runs synchronously (not queued), so a large list will take proportionally longer to respond — keep batches reasonably sized (max 1000 rows per request).
```json
{"openapi":"3.0.0","info":{"title":"Public API","version":"1.0"},"tags":[{"name":"Users"}],"servers":[{"url":"https://api-stage.hesh.tech"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"PublicUserAvatarSyncDto":{"type":"object","properties":{"items":{"minItems":1,"maxItems":1000,"description":"Rows to sync, each pairing an external_user_id with the avatar url to apply.","type":"array","items":{"$ref":"#/components/schemas/PublicUserAvatarSyncItemDto"}}},"required":["items"]},"PublicUserAvatarSyncItemDto":{"type":"object","properties":{"external_user_id":{"type":"string","description":"External identifier of the user whose avatar is being synced"},"avatar_url":{"type":"string","description":"Url of the avatar image to download"}},"required":["external_user_id","avatar_url"]},"PublicUserAvatarSyncReportDto":{"type":"object","properties":{"total":{"type":"number","description":"Number of input rows processed"},"updated":{"type":"number","description":"Number of users whose avatar was actually updated"},"skipped":{"description":"Rows that were not applied, with a reason each","type":"array","items":{"$ref":"#/components/schemas/PublicUserAvatarSyncSkippedItemDto"}}},"required":["total","updated","skipped"]},"PublicUserAvatarSyncSkippedItemDto":{"type":"object","properties":{"external_user_id":{"type":"string","description":"External identifier from the input row"},"avatar_url":{"type":"string","description":"Avatar url from the input row"},"reason":{"description":"Why this row was not applied","allOf":[{"$ref":"#/components/schemas/PublicUserAvatarSyncSkipReasonEnum"}]},"details":{"type":"string","nullable":true,"description":"Extra context — e.g. the matched internal user ids for a duplicate, or the download error message"}},"required":["external_user_id","avatar_url","reason"]},"PublicUserAvatarSyncSkipReasonEnum":{"type":"string","enum":["user_not_found","duplicate_external_user_id","user_inactive","avatar_already_set","url_unreachable"],"description":"Why this row was not applied"}}},"paths":{"/api/v1/public/users/avatars/sync":{"post":{"description":"\nTakes a list of `{ external_user_id, avatar_url }` rows (e.g. from a one-off import file) and, for each one, downloads the image and sets it as that user's avatar — synchronously, so the outcome of every row is in the response.\n\nA row is skipped (never overwrites anything) when:\n- `user_not_found` — no user in Hesh has this `external_user_id`.\n- `duplicate_external_user_id` — more than one Hesh user has this `external_user_id`; `details` lists the matched internal user ids for manual review.\n- `user_inactive` — the matched user's status is not Active.\n- `avatar_already_set` — the user already has an avatar; existing avatars are never replaced.\n- `url_unreachable` — the url could not be downloaded (unreachable, too large, or not an image); `details` carries the error.\n\nRuns synchronously (not queued), so a large list will take proportionally longer to respond — keep batches reasonably sized (max 1000 rows per request).\n","operationId":"PublicUsersController_syncAvatars_v1","parameters":[{"name":"x-tenant-id","in":"header","description":"Tenant id (uuid v4)","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicUserAvatarSyncDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicUserAvatarSyncReportDto"}}}},"429":{"description":"Returned when the rate limit is exceeded","headers":{"X-RateLimit-Limit":{"description":"Maximum number of allowed requests during the current window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining number of requests before throttling occurs","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Number of seconds until the rate limit window resets","schema":{"type":"integer"}}}}},"summary":"Bulk-sync user avatars from a list of urls, with a report","tags":["Users"]}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.hesh.app/manuals/public-api/users.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.