# Profile

Your profile is the user an API key acts for: name, email address and photo, plus which emails you want. Account API keys can read their own profile but not change one.

## The User object

The person, or account API key, the request acts for.

### Attributes

- `id` (string, required): Unique ID of the user, or of the account API key that is calling.
- `name` (string, required): The user's display name, or the account API key's name.
- `email` (string, required): The user's email address; empty for an account API key.
- `image` (nullable string, required): URL of the user's profile photo, or null. Always null for an account API key.
- `accountWorkspaceId` (string): Set when an account API key is calling: the workspace the key belongs to.
- `accountRole` (string, one of: `owner`, `admin`, `member`, `viewer`): Set when an account API key is calling: the role the key acts with.

### Example

```json
{
  "id": "Us3NfP8kLq2V",
  "name": "Maya Patel",
  "email": "maya@acme.dev",
  "image": "https://images.clankertest.com/users/Us3NfP8kLq2V/profile-Ph8KcV2nRx4M.webp"
}
```

## Get your profile

`GET /v1/me`

Returns the user the API key acts for. An account API key returns itself, with its workspace and role.

### Returns

Returns the [User](https://docs.qa.clankership.net/api/profile/object.md) object. The status is 200.

### Request

```bash
curl https://api.qa.clankership.net/v1/me \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Response

```json
{
  "id": "Us3NfP8kLq2V",
  "name": "Maya Patel",
  "email": "maya@acme.dev",
  "image": "https://images.clankertest.com/users/Us3NfP8kLq2V/profile-Ph8KcV2nRx4M.webp"
}
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.

## Update your profile

`PATCH /v1/me`

Sets your display name and records a `profile.updated` event in each workspace you belong to. Account API keys cannot change a profile.

### Parameters

- `name` (string, required): Your new display name.

### Returns

Returns an object with these fields. The status is 200.

- `ok` (boolean, required): Always true: the change was made. Always `true`.

### Request

```bash
curl -X PATCH https://api.qa.clankership.net/v1/me \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maya Patel"
  }'
```

### Response

```json
{
  "ok": true
}
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.

## Upload a profile photo

`POST /v1/me/photo`

Replaces your profile photo with a PNG, JPEG or WebP image under 5 MB. Account API keys cannot change a profile.

### Parameters

- `photo` (file, required): A PNG, JPEG or WebP image under 5 MB for your profile photo.

### Returns

Returns an object with these fields. The status is 200.

- `ok` (boolean, required): Always true: the photo was replaced. Always `true`.
- `image` (string, required): URL of your new profile photo.

### Request

```bash
curl -X POST https://api.qa.clankership.net/v1/me/photo \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -F "photo=@photo.png"
```

### Response

```json
{
  "ok": true,
  "image": "https://images.clankertest.com/users/Us3NfP8kLq2V/profile-Ph8KcV2nRx4M.webp"
}
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.

## Get your notification preferences

`GET /v1/me/preferences`

Returns which emails you want, or the defaults if you never saved any. Account API keys have no preferences.

### Returns

Returns an object with these fields. The status is 200. Which emails you want. A user who never saved preferences gets the defaults.

- `userId` (string, required): Your user ID.
- `productUpdates` (boolean, required): Whether to email you Clanker Ship product updates. Defaults to true.
- `workspaceActivity` (boolean, required): Whether to email you activity in your workspaces. Defaults to false.

### Request

```bash
curl https://api.qa.clankership.net/v1/me/preferences \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Response

```json
{
  "userId": "Us3NfP8kLq2V",
  "productUpdates": true,
  "workspaceActivity": false
}
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.

## Update your notification preferences

`PATCH /v1/me/preferences`

Saves both email preferences, so send both fields. Account API keys have no preferences.

### Parameters

- `productUpdates` (boolean, required): Whether to email you Clanker Ship product updates. Defaults to true.
- `workspaceActivity` (boolean, required): Whether to email you activity in your workspaces. Defaults to false.

### Returns

Returns an object with these fields. The status is 200.

- `ok` (boolean, required): Always true: the change was made. Always `true`.

### Request

```bash
curl -X PATCH https://api.qa.clankership.net/v1/me/preferences \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productUpdates": false,
    "workspaceActivity": true
  }'
```

### Response

```json
{
  "ok": true
}
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.

## Get your home path

`GET /v1/me/home`

Returns the website path to open after sign-in: `/w/{slug}` for a workspace you belong to, or `/onboarding` when you belong to none. It first adds you to every workspace whose allowed domains include your email's domain.

### Returns

Returns a string. The status is 200. A website path, such as /w/acme or /onboarding.

### Request

```bash
curl https://api.qa.clankership.net/v1/me/home \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Response

```json
"/w/acme"
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.

## Get your onboarding workspace

`GET /v1/me/onboarding`

Returns a workspace you already belong to, or `existing: null` when you belong to none. It first adds you to every workspace whose allowed domains include your email's domain.

### Returns

Returns an object with these fields. The status is 200.

- `existing` (nullable object, required): A workspace you already belong to, or null when you should create one. See [the Workspace object](https://docs.qa.clankership.net/api/workspaces/object.md).
  - `id` (string, required): Unique ID of the workspace.
  - `name` (string, required): The workspace's display name.
  - `slug` (string, required): The workspace's URL name: 2 to 48 lowercase letters, digits and hyphens, such as acme.
  - `iconUrl` (nullable string, required): URL of the workspace's icon image, or null.
  - `role` (string, one of: `owner`, `admin`, `member`, `viewer`, required): Your role in the workspace: owner, admin, member or viewer.

### Request

```bash
curl https://api.qa.clankership.net/v1/me/onboarding \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Response

```json
{
  "existing": {
    "id": "Wk7Qm2RtXa9L",
    "name": "Acme",
    "slug": "acme",
    "iconUrl": "https://images.clankertest.com/workspaces/Wk7Qm2RtXa9L/icon-Ic5TfR2mWq8Z.png",
    "role": "owner"
  }
}
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.