Worklyn Docs

Assistant

Copy as MarkdownView MarkdownOpen in ClaudeOpen in ChatGPT

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:

CredentialHow to send it
Session tokenAuthorization: Bearer <token>, or the id cookie set when the person signs in at worklyn.me
OAuth access tokenAuthorization: Bearer <token>
App tokenAuthorization: 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.

FieldTypeMeaning
idstringThe assistant's id. It stays the same for the life of the account.
namestringThe name the assistant is shown by.
emailstring or nullThe assistant's own mail address. null until a POST has made its mailbox.
createdbooleantrue when this call made the assistant, its mailbox, or both. Always false on a GET.

Get the assistant

GET /assistant

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

Answered 200:

{
  "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.

FieldTypeMeaning
namestring, optionalThe name to make the assistant with. At most 24 characters. Spaces at the ends are dropped.
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:

{
  "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.

{
  "ok": false,
  "code": "invalid",
  "error": "a name holds at most 24 characters"
}
StatusCodeWhen
400invalidThe body is not JSON, name is not a string, or it is longer than 24 characters. Nothing is written.
401unauthorisedThe credentials are missing or not valid.
404notFoundGET only: the account has no assistant yet.
503busyThe mailbox could not be made just now. Nothing is written. Send the same request again.

For machines