Invite a person by email
Email someone a link to join your organisation, with a role. They need no account beforehand. Takes a signed-in console session, never an API key.
POST
/
invitations
# cookies.txt holds the cookies from your signed-in console session.
curl --request POST "$MITHUNAI_URL/mithunai/api/v1/invitations" \
--cookie cookies.txt \
--header "X-CSRF-Token: $MITHUNAI_CSRF_TOKEN" \
--header "Content-Type: application/json" \
--data '{"email": "sarah.chen@example.com", "role": "editor"}'
import os
from http.cookiejar import MozillaCookieJar
import requests
jar = MozillaCookieJar("cookies.txt")
jar.load()
response = requests.post(
f"{os.environ['MITHUNAI_URL']}/mithunai/api/v1/invitations",
cookies=jar,
headers={"X-CSRF-Token": os.environ["MITHUNAI_CSRF_TOKEN"]},
json={"email": "sarah.chen@example.com", "role": "editor"},
timeout=30,
)
response.raise_for_status()
print(response.json()["id"])
// Runs in a page on the MITHUNAI console's own origin, while signed in.
// csrfToken is the value of the csrf_token cookie.
const response = await fetch('/mithunai/api/v1/invitations', {
method: 'POST',
credentials: 'include',
headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': csrfToken },
body: JSON.stringify({ email: 'sarah.chen@example.com', role: 'editor' }),
})
console.log((await response.json()).id)
{
"id": "9d4e2a71-3c5b-4f80-a6d1-8e7b2c0f4a13",
"email": "sarah.chen@example.com",
"role": "editor",
"status": "pending",
"invited_by_name": "Alex Mercer",
"created_at": "2026-10-13T09:12:05.640021+00:00",
"expires_at": "2026-10-20T09:12:05.640021+00:00",
"last_sent_at": "2026-10-13T09:12:05.640021+00:00"
}
{ "code": "conflict", "message": "That address already has an invitation. Re-send it instead." }
{ "code": "dependency_failure", "message": "This deployment cannot send e-mail yet." }
Emails an invitation to join your organisation. The person does not need an account: they open the link, choose a password, and their account and membership are created together. If the address already has an account, they confirm with that account’s password and are added to your organisation.
The link works once and for seven days. It is sent only to the address you give and is never returned by this API.
The response is the same whether or not the address already has an account, so this endpoint cannot be used to find out who is registered.
This endpoint takes a signed-in console session, not an API key. Send the session cookies your browser received when you signed in, plus the
X-CSRF-Token header set to the value of the csrf_token cookie. A request authenticated with an mithunai_sk_ key is refused with 403.
You need the owner or admin role, and you cannot invite to a role above your own; asking for one returns 403. Ownership is never given by invitation, so owner returns 400.
409— the address is already a member of your organisation, or already has an invitation that has not been accepted. Send that one again instead.429— your organisation has sent 30 invitations in the last hour. Wait and try again.503— this deployment is not set up to send email. Nothing was created; ask whoever runs the deployment.502— the email provider refused the message. Nothing was created; try again shortly.
string
required
The value of your session’s
csrf_token cookie (named __Host-csrf_token when the console is
served over HTTPS without a shared cookie domain). A missing or mismatched token returns 401.string
required
The address to invite. Up to 255 characters. It is stored and matched in lower case.
string
default:"normal"
The role they get when they accept:
admin, editor, normal or dataset_operator. normal is
the member role. See Organisations and roles.Response
Returns201 Created with the invitation. The email has been handed to the email provider by the time you receive it.
string
required
The invitation’s ID (UUID). Use it to send the invitation again or withdraw it.
string
required
The invited address, in lower case.
string
required
The role the person will get.
string
required
pending while the link works; expired once its seven days have passed.string | null
required
The display name of the member who sent it.
string
required
When it was first sent, ISO 8601 in UTC.
string
required
When the current link stops working, ISO 8601 in UTC.
string
required
When it was last sent, ISO 8601 in UTC.
# cookies.txt holds the cookies from your signed-in console session.
curl --request POST "$MITHUNAI_URL/mithunai/api/v1/invitations" \
--cookie cookies.txt \
--header "X-CSRF-Token: $MITHUNAI_CSRF_TOKEN" \
--header "Content-Type: application/json" \
--data '{"email": "sarah.chen@example.com", "role": "editor"}'
import os
from http.cookiejar import MozillaCookieJar
import requests
jar = MozillaCookieJar("cookies.txt")
jar.load()
response = requests.post(
f"{os.environ['MITHUNAI_URL']}/mithunai/api/v1/invitations",
cookies=jar,
headers={"X-CSRF-Token": os.environ["MITHUNAI_CSRF_TOKEN"]},
json={"email": "sarah.chen@example.com", "role": "editor"},
timeout=30,
)
response.raise_for_status()
print(response.json()["id"])
// Runs in a page on the MITHUNAI console's own origin, while signed in.
// csrfToken is the value of the csrf_token cookie.
const response = await fetch('/mithunai/api/v1/invitations', {
method: 'POST',
credentials: 'include',
headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': csrfToken },
body: JSON.stringify({ email: 'sarah.chen@example.com', role: 'editor' }),
})
console.log((await response.json()).id)
{
"id": "9d4e2a71-3c5b-4f80-a6d1-8e7b2c0f4a13",
"email": "sarah.chen@example.com",
"role": "editor",
"status": "pending",
"invited_by_name": "Alex Mercer",
"created_at": "2026-10-13T09:12:05.640021+00:00",
"expires_at": "2026-10-20T09:12:05.640021+00:00",
"last_sent_at": "2026-10-13T09:12:05.640021+00:00"
}
{ "code": "conflict", "message": "That address already has an invitation. Re-send it instead." }
{ "code": "dependency_failure", "message": "This deployment cannot send e-mail yet." }
Last modified on November 3, 2026
# cookies.txt holds the cookies from your signed-in console session.
curl --request POST "$MITHUNAI_URL/mithunai/api/v1/invitations" \
--cookie cookies.txt \
--header "X-CSRF-Token: $MITHUNAI_CSRF_TOKEN" \
--header "Content-Type: application/json" \
--data '{"email": "sarah.chen@example.com", "role": "editor"}'
import os
from http.cookiejar import MozillaCookieJar
import requests
jar = MozillaCookieJar("cookies.txt")
jar.load()
response = requests.post(
f"{os.environ['MITHUNAI_URL']}/mithunai/api/v1/invitations",
cookies=jar,
headers={"X-CSRF-Token": os.environ["MITHUNAI_CSRF_TOKEN"]},
json={"email": "sarah.chen@example.com", "role": "editor"},
timeout=30,
)
response.raise_for_status()
print(response.json()["id"])
// Runs in a page on the MITHUNAI console's own origin, while signed in.
// csrfToken is the value of the csrf_token cookie.
const response = await fetch('/mithunai/api/v1/invitations', {
method: 'POST',
credentials: 'include',
headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': csrfToken },
body: JSON.stringify({ email: 'sarah.chen@example.com', role: 'editor' }),
})
console.log((await response.json()).id)
{
"id": "9d4e2a71-3c5b-4f80-a6d1-8e7b2c0f4a13",
"email": "sarah.chen@example.com",
"role": "editor",
"status": "pending",
"invited_by_name": "Alex Mercer",
"created_at": "2026-10-13T09:12:05.640021+00:00",
"expires_at": "2026-10-20T09:12:05.640021+00:00",
"last_sent_at": "2026-10-13T09:12:05.640021+00:00"
}
{ "code": "conflict", "message": "That address already has an invitation. Re-send it instead." }
{ "code": "dependency_failure", "message": "This deployment cannot send e-mail yet." }