Markhub API

Quick start

1. In Markhub, open the workspace menu and go to Settings, then API.
2. Click Issue key. Pick the Hub the key posts into and the scopes it needs.
3. Copy the key. It starts with mk_live_ and is shown only once, so store it as a server secret right away.
4. Send your first message:

curl -X POST https://makigql.shop/api/public/v1/messages \
  -H "Authorization: Bearer $MARKHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"**Deploy finished**: api v2.14.0 is live."}'

The message shows up in the Hub right away, posted by your workspace's MAKi bot.

Authentication

Every endpoint lives under https://makigql.shop/api/public/v1. Send the key as a Bearer token on each request:

Authorization: Bearer mk_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

• Keep the key on your server, in an environment variable or secret manager. Never ship it to a browser or a mobile app.
• One key posts into one Hub. To post into several Hubs, issue one key per Hub.
• Scopes decide what a key can create: Create message, Create note, Create todo. Calling an endpoint outside the key's scopes returns 403.
• Rotate issues a new key and keeps the old one working for 24 hours, so you can swap it without downtime. Revoke stops a key immediately.

Post a message

POST /api/public/v1/messages · scope Create message

{ "text": "**payment-worker** crashed on prod (exit 137). Restarting." }

{
  "success": true,
  "data": {
    "id": "5a85019d-…",
    "conversationId": "2c0683cf-…",
    "createdAt": "2026-09-11T12:24:05.092Z"
  }
}

Create a note

POST /api/public/v1/notes · scope Create note

{
  "title": "Nightly report 2026-09-11",
  "content": "## Orders\n- 1,240 shipped\n- 17 late (1.4%)"
}

{
  "success": true,
  "data": { "id": "…", "bucketId": "…", "createdAt": "…" }
}

Create a to-do

POST /api/public/v1/todos · scope Create todo

{
  "title": "Investigate 5xx spike on /checkout",
  "content": "Started 02:14 UTC.",
  "dueDate": "2026-09-12T09:00:00Z",
  "priority": "HIGH"
}

{
  "success": true,
  "data": { "id": "…", "bucketId": "…", "createdAt": "…" }
}

Code examples

await fetch("https://makigql.shop/api/public/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MARKHUB_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "Nightly sync done. 1,240 orders imported." }),
});

import os, requests

requests.post(
    "https://makigql.shop/api/public/v1/messages",
    headers={"Authorization": f"Bearer {os.environ['MARKHUB_API_KEY']}"},
    json={"text": "Nightly sync done. 1,240 orders imported."},
    timeout=10,
)

Errors and limits

Each key can make 60 requests per minute. Past that, the key is blocked for 5 minutes and requests return 403 with a Retry-After header in seconds.

Errors come back as JSON. Branch on statusCode; message is a readable reason meant for logs.

{
  "statusCode": 403,
  "message": "…",
  "timestamp": "2026-09-11T12:24:31.033Z",
  "path": "/api/public/v1/messages"
}

A retried request posts again. If your sender retries on timeouts, include a run ID or similar marker in the text so duplicates are easy to spot.

What your team sees

• Posts come from your workspace's MAKi bot and appear in real time for everyone in the Hub, in the Hub and in the Stream.
• Teammates can reply, react, or turn a message into a to-do or note, like any other message.
• Each post records which key sent it, so you can tell integrations apart.

Questions or a use case this doesn't cover? Email admin@markhub.ink.