Gná API guide for bots and scripts

Anything that can make an HTTP request can post to a Gná conversation and read the replies: a shell script, a cron job, Home Assistant, a camera, a bot in any language. This guide covers everything an integration can do. The examples use https://api.gna.rymdvarel.se; use your own server's address.

Gná is named after the messenger of Norse mythology who carries Frigg's errands between the worlds. In code and URLs the name is written gna.

Tokens

Each conversation has its own tokens. Create one in the app (the conversation's settings, New token) or with gna token create on the server. The token is shown once; it starts with gna_. Send it with every request:

Authorization: Bearer gna_…

The token decides the conversation, so requests never name one. A bot holding a token sees only that conversation.

Give each bot or script its own token, named after it. You can then revoke one without breaking the others, and the app shows which token sent each message. Revoking a token, or deleting the conversation, makes every request with it fail with 401.

To check a token and see its conversation:

curl -H "Authorization: Bearer $GNA_TOKEN" https://api.gna.rymdvarel.se/me
{
  "kind": "integration",
  "token": {"id": "tok_lusab-babad", "name": "garage script", "send_only": false,
            "created_at": "2026-11-21T10:00:00Z", "last_used_at": "2026-11-21T10:05:00Z",
            "revoked_at": null},
  "conversation": {"id": "conv_gutih-tugad", "name": "Garage", "encrypted": false}
}

Sending messages

POST /messages with a JSON body:

curl -H "Authorization: Bearer $GNA_TOKEN" -H "Content-Type: application/json" \
  -d '{"text": "Backup finished: 42 GB in 18 minutes"}' \
  https://api.gna.rymdvarel.se/messages

The answer (201) is the stored message; its id is what replies and button presses refer to. Messages from integrations appear under the conversation's name; sender.token_name says which token sent it.

Field Type Default Meaning
text string, 1–4096 characters The message. Plain text; line breaks are kept.
silent boolean false Notify without sound, and without lighting up the screen.
reply_to message ID Show the message as a reply, quoting that message. It must be in this conversation.
buttons rows of buttons [] See Buttons.
buttons_single_use boolean true See Buttons.
notification_buttons "ok", "yes_no", "ok_cancel" See Buttons in notifications.
attachments attachment IDs, at most 10 [] Images uploaded earlier. See Images.
image_url URL An image for the server to fetch. See Images.

A message needs text, an image, or both. Unknown fields are rejected, so a typo fails instead of being ignored.

The phone gets a notification, titled with the conversation's name, unless the user has muted the conversation or has the app open.

Buttons

Buttons are rows: up to 8 rows of up to 8 buttons each.

curl -H "Authorization: Bearer $GNA_TOKEN" -H "Content-Type: application/json" \
  -d '{"text": "Front door is unlocked. Lock it?",
       "buttons": [[{"label": "Lock", "data": "lock"}, {"label": "Ignore", "data": "ignore"}],
                   [{"label": "Open camera", "url": "https://camera.example.com/front"}]]}' \
  https://api.gna.rymdvarel.se/messages

Each button has a label (1–64 characters) and exactly one of:

Callback buttons are single-use by default: after the first press the app shows which one was chosen and disables them all, so a double tap cannot lock and unlock the door. With "buttons_single_use": false they stay pressable and every press reaches your bot.

A message with callback buttons nobody has pressed stays on the server for up to 7 days (see What the server keeps), so the button still works when the user gets to it.

Buttons in notifications

iOS only shows buttons in a notification if the app registered them beforehand, with fixed labels. Gná has three sets. Choose one with notification_buttons, and put matching callback buttons first in the first row:

notification_buttons Notification shows Needs, at the start of the first row
"ok" OK 1 callback button
"yes_no" Yes, No 2 callback buttons
"ok_cancel" OK, Cancel 2 callback buttons

The notification's first action presses the first button, the second the second. Inside the app the message shows your own labels and all its buttons. Without notification_buttons, the notification offers Reply, which sends a text reply to your message.

{"text": "Garage door has been open for 30 minutes. Close it?",
 "notification_buttons": "yes_no",
 "buttons": [[{"label": "Close", "data": "close"}, {"label": "Leave open", "data": "leave"}]]}

Images

JPEG, PNG, GIF and WebP, up to 20 MB and 50 megapixels (the server's operator can change both). The server checks that the file really is an image, removes metadata such as GPS location, and makes a thumbnail for notifications. There are three ways to send one.

With the message, in one request (multipart; the file field is image):

curl -H "Authorization: Bearer $GNA_TOKEN" \
  -F text="Motion at the front door" -F image=@snapshot.jpg \
  https://api.gna.rymdvarel.se/messages

The other form fields are silent, reply_to, buttons (as a JSON string), buttons_single_use and notification_buttons.

Upload first, then refer to it (the file field is file), for example to send several images in one message:

curl -H "Authorization: Bearer $GNA_TOKEN" -F file=@front.jpg https://api.gna.rymdvarel.se/attachments
# → {"id": "att_…", "content_type": "image/jpeg", "width": 1920, "height": 1080, …}

curl -H "Authorization: Bearer $GNA_TOKEN" -H "Content-Type: application/json" \
  -d '{"text": "Both doors", "attachments": ["att_…", "att_…"]}' \
  https://api.gna.rymdvarel.se/messages

An upload that is not used in a message within an hour is deleted.

Let the server fetch it with image_url. Useful for a camera's snapshot URL: the camera needs no extra step, and the phone never contacts it.

curl -H "Authorization: Bearer $GNA_TOKEN" -H "Content-Type: application/json" \
  -d '{"text": "Motion at the front door", "image_url": "http://192.168.1.50/snapshot.jpg"}' \
  https://api.gna.rymdvarel.se/messages

The server fetches the image while handling your request (5 seconds at most, following up to 3 redirects on the same host). Private network addresses such as 192.168.… are only fetched if the conversation's Allow internal URLs setting is on, which the server's operator can forbid; localhost and link-local addresses never are.

If fetching fails the message is still sent, with its text, and image_fetch_error in the answer says why: invalid_url, dns_failed, blocked_address (an internal address the conversation does not allow), redirect_blocked, too_many_redirects, timeout, connection_failed, http_error, too_large, invalid_image, unsupported_image_type, image_too_large, processing_failed or fetch_failed.

Receiving replies and button presses

Your bot asks GET /updates for what happened after the last event it has seen. The request waits until something happens, or until timeout seconds have passed (a long-poll), so a bot reacts at once without hammering the server.

curl -H "Authorization: Bearer $GNA_TOKEN" \
  "https://api.gna.rymdvarel.se/updates?after=0&timeout=30"

Here the user replied to a question and then pressed its Lock button (messages trimmed to the interesting fields; they carry the same fields as the answer to POST /messages):

{
  "events": [
    {
      "id": 4813,
      "type": "message",
      "conversation_id": "conv_gutih-tugad",
      "message": {
        "id": 4813,
        "sender": {"kind": "user", "name": "Johan", "token_id": null, "token_name": null},
        "text": "Lock it",
        "reply_to": {"id": 4812, "sender": "Garage", "excerpt": "Front door is unlocked. Lock it?",
                     "has_image": false, "deleted": false},
        "attachments": []
      },
      "callback": null
    },
    {
      "id": 4815,
      "type": "callback",
      "conversation_id": "conv_gutih-tugad",
      "message": {
        "id": 4812,
        "text": "Front door is unlocked. Lock it?",
        "buttons_disabled": true,
        "pressed": {"row": 0, "col": 0, "label": "Lock", "pressed_at": "2026-11-21T10:06:12Z"}
      },
      "callback": {
        "message_id": 4812, "row": 0, "col": 0, "label": "Lock", "data": "lock",
        "user": {"id": "acc_lusab-babad", "name": "Johan"},
        "pressed_at": "2026-11-21T10:06:12Z"
      }
    }
  ],
  "next": 4815
}

Then ask again with after set to next. An empty events list means the wait ran out; ask again with the same after.

There are two kinds of event:

Your own messages are not included.

Parameter Default Meaning
after 0 Return events with an ID above this.
timeout 30 Seconds to wait when nothing has happened yet. At most 60; 0 answers at once.
limit 100 Most events per answer (1–500).

Set your HTTP client's timeout longer than timeout, say 40 seconds for timeout=30.

While your bot is waiting on /updates, the app shows it as online.

Remember where you are

Asking for what follows after tells the server you have handled everything up to it. Keep next somewhere that survives a restart (a file is enough). A bot that starts again from after=0 receives, a second time, every event the server still has.

What the server keeps

Gná relays messages; the app keeps the history. The server deletes a message 10 minutes after the user's devices and every bot reading the conversation have fetched it, and after 7 days in any case. So /updates brings what is new, not the conversation's history.

A read token holds messages back until its bot has fetched them, as long as the token has been used in the last 7 days. A token that is not used for 7 days, or a send-only token, does not.

Seeing everything

GET /messages (same parameters, read tokens only) returns everything in the conversation instead, your own messages included, plus message_updated events when a message changes (for example when its buttons are pressed). Most bots want /updates.

A complete bot in Python

No libraries needed. Set GNA_TOKEN, and run it: it asks whether to lock the door, answers the button, and answers ping with pong.

"""A minimal Gná bot."""

import json
import os
import pathlib
import time
import urllib.error
import urllib.request

SERVER = "https://api.gna.rymdvarel.se"
TOKEN = os.environ["GNA_TOKEN"]
CURSOR = pathlib.Path("gna-cursor.txt")


def call(method, path, body=None, timeout=10):
    request = urllib.request.Request(
        SERVER + path,
        data=None if body is None else json.dumps(body).encode(),
        method=method,
        headers={"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"},
    )
    with urllib.request.urlopen(request, timeout=timeout) as response:
        return json.load(response)


def send(text, **fields):
    return call("POST", "/messages", {"text": text, **fields})


def handle(event):
    message = event["message"]
    if event["type"] == "callback":
        if event["callback"]["data"] == "lock":
            send("Locked.", reply_to=message["id"])
        else:
            send("Leaving it unlocked.", reply_to=message["id"])
    elif (message["text"] or "").strip().lower() == "ping":
        send("pong", reply_to=message["id"])


def main():
    after = int(CURSOR.read_text()) if CURSOR.exists() else 0
    send(
        "Front door is unlocked. Lock it?",
        notification_buttons="yes_no",
        buttons=[[{"label": "Lock", "data": "lock"}, {"label": "Ignore", "data": "ignore"}]],
    )
    while True:
        try:
            batch = call("GET", f"/updates?after={after}&timeout=30", timeout=40)
        except urllib.error.HTTPError as error:
            if error.code in (401, 403):
                raise  # Revoked or send-only token: retrying will not help.
            time.sleep(5)
            continue
        except OSError:  # Network trouble or a timeout: try again shortly.
            time.sleep(5)
            continue
        for event in batch["events"]:
            handle(event)
        after = batch["next"]
        CURSOR.write_text(str(after))


if __name__ == "__main__":
    main()

Errors

Errors answer with an HTTP status and a body like:

{"error": "empty_message", "detail": "message needs text, attachments or image_url"}

error is a stable code to act on; detail is for people (for 422 it lists each problem with the field it concerns).

Status error Meaning
400 empty_message Neither text nor an image.
400 invalid Something else is wrong, such as reply_to naming another conversation's message or notification_buttons without matching buttons; detail says what.
400 invalid_image, unsupported_image_type, image_too_large, processing_failed An uploaded file is not an image, not a supported type, has too many pixels, or could not be processed.
401 unauthorized Missing, unknown or revoked token, or the conversation was deleted.
403 send_only A send-only token tried to read.
403 forbidden The endpoint is for the app, not for tokens.
413 too_large The request or image is too big.
415 unsupported_media_type POST /messages takes application/json or multipart/form-data.
422 validation_error The body does not match the fields above.
429 demo_limit Demo accounts only: too many messages this hour.

Retry on network errors and 5xx, with a pause. Do not retry 4xx unchanged: the same request fails the same way.

Limits

What Limit
text 4096 characters
Buttons 8 rows of 8; label 64 characters, data 256, url 2048
Images per message 10
Image size 20 MB and 50 megapixels by default
image_url fetch 5 seconds, 3 redirects on the same host
Long-poll timeout 60 seconds by default
Unused uploads Deleted after an hour
Messages on the server 10 minutes after delivery, 7 days at most

The size, time and retention limits are defaults the server's operator can change.

Encrypted conversations

A conversation created as encrypted rejects text: messages carry ciphertext, nonce and key_version instead, and images are not supported yet. Encryption needs a client library, so the examples here are for ordinary conversations.

Reference

Every endpoint, with its fields and answers, is in the server's OpenAPI description at /openapi.json, which you can browse and try at /docs. Those endpoints that need an app session rather than a token are for the Gná app.