> Worklyn documentation. Index for language models: https://worklyn.com/llms.txt

# Assistant

Every Worklyn account has one assistant: its own AI, with a name and a mail address of its own. Use this endpoint to read the assistant an account has, or to make it for an account that has none.

- `GET /assistant` answers the assistant the account has. It never makes anything.
- `POST /assistant` answers it too, and first makes whatever is missing: the assistant, its mailbox, or both.

The base address is `https://worklyn.com`. Requests and answers are JSON.

## Authentication

Both calls act on the account the credentials name. There is no account id in the address or the body, so one account can never read or make another account's assistant.

Send one of these with every request:

| Credential | How to send it |
|---|---|
| Session token | `Authorization: Bearer <token>`, or the `id` cookie set when the person signs in at worklyn.me |
| OAuth access token | `Authorization: Bearer <token>` |
| App token | `Authorization: Bearer <token>` together with `X-App-Id: <app id>` |

A request with no credentials, or with ones that are not valid, is answered `401` with the code `unauthorised`.

## The assistant

Both calls answer the same object.

| Field | Type | Meaning |
|---|---|---|
| `id` | string | The assistant's id. It stays the same for the life of the account. |
| `name` | string | The name the assistant is shown by. |
| `email` | string or null | The assistant's own mail address. `null` until a `POST` has made its mailbox. |
| `created` | boolean | `true` when this call made the assistant, its mailbox, or both. Always `false` on a `GET`. |

## Get the assistant

`GET /assistant`

```bash
curl https://worklyn.com/assistant \
  -H "Authorization: Bearer $WORKLYN_TOKEN"
```

Answered `200`:

```json
{
  "id": "3f6ebe66-89f7-468b-bf58-098a8aebf89a",
  "name": "Mimi",
  "email": "mimi@worklyn.me",
  "created": false
}
```

An account that has no assistant yet is answered `404` with the code `notFound`. Nothing is made: send a `POST` to make it.

## Create the assistant

`POST /assistant`

The body may be left out. It has one optional field.

| Field | Type | Meaning |
|---|---|---|
| `name` | string, optional | The name to make the assistant with. At most 24 characters. Spaces at the ends are dropped. |

```bash
curl -X POST https://worklyn.com/assistant \
  -H "Authorization: Bearer $WORKLYN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Kora Bloom"}'
```

Answered `201` when something was made:

```json
{
  "id": "0b54e0f4-2c0e-8d4a-9c53-4f1d6f6b2a17",
  "name": "Kora Bloom",
  "email": "korabloom@worklyn.me",
  "created": true
}
```

Answered `200` when the account already had its assistant and its mailbox. The answer is the same object with `created: false`, and nothing is changed.

The call is safe to send again. An account gets one assistant and one mailbox, however many times it is sent.

### How the name is chosen

- An assistant the account already has keeps its name. A `name` sent is ignored.
- A new assistant takes the name the account already keeps for its AI, when it has one.
- Otherwise it takes the `name` sent.
- With no name at all it is called "Artificial intelligence".

### How the mail address is chosen

The address is `<handle>@worklyn.me`. The handle is the name in lowercase, keeping only letters, digits and hyphens, so "Kora Bloom" is `korabloom@worklyn.me`.

A generated address such as `lunafrost@worklyn.me` is made instead when:

- the assistant has no name of its own,
- the name cannot be a handle (a handle is 3 to 32 characters), or
- that address is already taken.

The name is not changed when the address is generated. An address that already exists is never handed to another account.

## Errors

An error is answered as JSON with a code and a sentence for a person.

```json
{
  "ok": false,
  "code": "invalid",
  "error": "a name holds at most 24 characters"
}
```

| Status | Code | When |
|---|---|---|
| `400` | `invalid` | The body is not JSON, `name` is not a string, or it is longer than 24 characters. Nothing is written. |
| `401` | `unauthorised` | The credentials are missing or not valid. |
| `404` | `notFound` | `GET` only: the account has no assistant yet. |
| `503` | `busy` | The mailbox could not be made just now. Nothing is written. Send the same request again. |

## For machines

- This page as Markdown: [https://worklyn.com/docs/assistant.md](https://worklyn.com/docs/assistant.md)
- The whole API, machine-readable: [https://worklyn.com/openapi.json](https://worklyn.com/openapi.json)
- An index of Worklyn for language models: [https://worklyn.com/llms.txt](https://worklyn.com/llms.txt)