> ## Documentation Index
> Fetch the complete documentation index at: https://handbook.nyotaimara.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/auth/avatar — Upload a Profile Avatar Image

> Upload a profile photo before account creation using multipart/form-data. The server returns a public CDN URL to include in your registration payload.

Upload a profile photo during the registration flow, before the user's account has been fully created. The file is stored and a public CDN URL is returned immediately. Pass this URL in your registration payload so it is saved to the user record on account creation.

**POST** `/v1/auth/avatar`

No authentication required.

## Request

The request must be sent as `multipart/form-data`.

<ParamField body="avatar" type="file" required>
  The image file to upload. Common formats are accepted (JPEG, PNG, WebP). The original file extension is preserved in the stored filename.
</ParamField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url "https://api.nyotaimara.com/v1/auth/avatar" \
    --form "avatar=@/path/to/photo.jpg"
  ```
</CodeGroup>

## Response

<ResponseField name="success" type="boolean" required>
  `true` when the upload completed successfully.
</ResponseField>

<ResponseField name="avatarUrl" type="string" required>
  A public CDN URL pointing to the uploaded image. Store this value and include it in your subsequent registration request.
</ResponseField>

```json theme={null}
{
  "success": true,
  "avatarUrl": "https://cdn.nyotaimara.com/avatars/user-1714000000000-abc123.jpg"
}
```

<Note>
  **Error cases**

  | Status | Error                     | Description                                       |
  | ------ | ------------------------- | ------------------------------------------------- |
  | 400    | `No avatar file provided` | The `avatar` field is missing from the form data. |
  | 500    | `Failed to upload avatar` | An unexpected error occurred during upload.       |
</Note>