Magma APIs

An overview of Magma's two developer APIs: the REST API for running your Artspaces, and webhooks for automated chat bots that help your community grow.

Magma has two ways to build on top of your community: run your Artspaces from your own tools, and add automated bots that bring new experiences to your members, like art levels, contests, welcome messages or daily drawing themes. Both are plain HTTPS and JSON, served from https://magma.com/api.

#REST API

Use a personal API key to do from code what you do in the Magma app: list your Artspaces and channels, create drawings and folders, upload images as new drawings, move files and manage Artspace members.

• Authentication: a personal API key in the Authorization: Bearer header.
• Get a key: Account & Billing > API > Generate API key.
• Available on all plans (a verified email is required on the free plan). Paid plans get a higher rate limit.

Read the REST API guide

#Artspace bots and chat webhooks

Connect an automated bot or service to your Artspace chat. Post messages, reactions and typing indicators through a webhook URL, and have Magma send signed events to your server when people write in your channels.

• Authentication: a secret token in the webhook URL. Outgoing events are signed with HMAC-SHA256.
• Set it up: Artspace Settings > Webhooks > Create Webhook (needs the Manage artspace permission).

Read the Artspace bots and webhooks guide

#Which one do I need?

#Questions?

If something in these guides doesn't work as described, contact Magma support at support@magma.com.

Magma REST API: getting started with API keys

Create a personal API key and use Magma's REST API to read and manage your Artspaces, channels, members, drawings and folders.

The Magma REST API lets your own tools do many of the things you do in the Magma app: list your Artspaces, create channels, create or upload drawings, move files around and manage Artspace members. It's a plain HTTPS + JSON API, so it works with curl, Python, Node.js or any other HTTP client.

#Who this is for

• Community builders and technical artists who want to create new experiences for their Artspace (for example, opening a canvas for every weekly contest, or giving members a new role when they reach the next art level).
• Artspace admins who want to manage members and channels in bulk.

If you want an automated bot that posts into Artspace chat, or you want Magma to notify your server when someone writes in a channel, see Artspace bots and chat webhooks instead.

#A few terms

The API uses some older names from Magma's code. Here's how they match what you see in the app:

Each drawing or folder has two IDs: a database ID (_id, 24 hex characters) and a shortId (10 characters). Endpoints say which one they accept.

#Before you start

• You need a registered Magma account. Guest accounts can't open the API settings.
• Your email address must be verified, unless you're on a paid plan. Without a verified email you can't create a key, and existing keys won't authenticate.
• API access is not limited to paid plans, but paid plans get a higher rate limit (see "Limits" below).
• What you can do through the API is exactly what your account can do in the app. For example, creating a channel needs the "Create new channels" permission in that Artspace.

#Step 1: Create your API key

1. In Magma, open your user menu and choose Account & Billing. You can also go straight to https://magma.com/my/account/api.
2. Open the API tab. The section is called Personal access tokens.
3. If you don't have a key yet, click Generate API key.
4. Your key appears in the table. Click it to copy it to your clipboard.

Each key has a Scope of "All": it can do anything your account can do. Treat it like a password.

To manage a key later, open the ⋮ menu next to it:

• Refresh replaces the key with a new one. The old key stops working right away.
• Remove deletes the key.

#Step 2: Authenticate

Send your key in the Authorization header as a Bearer token on every request:

Authorization: Bearer YOUR_API_KEY

We also recommend sending Accept: application/json, so that error responses come back as JSON.

#Base URL

All endpoints live under:

https://magma.com/api

#Step 3: Make your first call

Check that your key works by fetching your own profile:

curl https://magma.com/api/profile \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

#How responses look

Successful responses are wrapped in a standard envelope. The data you asked for is in data:

{
  "hash": "a6323ff",
  "processingTime": 12,
  "statusCode": 200,
  "data": {
    "_id": "66f1c2a9e4b0a1d2c3f40001",
    "userType": "user",
    "username": "inkfox",
    "name": "Ink Fox",
    "email": "inkfox@example.com",
    "createdAt": "2025-03-14T09:26:53.000Z"
  }
}

The data example above is shortened; the real profile has more fields. Update and delete calls often return only the envelope, with no data field. hash identifies the server build and processingTime is in milliseconds; you can ignore both.

#Endpoint reference

Paths are relative to https://magma.com. "Permission" is the Artspace role permission (as named in Artspace Settings > Roles) that your account needs.

#Profile

#Artspaces

{userId} is the member's user ID (user._id in the members list).

When you set a member's roles, the list replaces all of their current roles. It must include the ID of the role whose type is everyone (or owner, if the member is the owner); otherwise the request fails with 400.

#Channels

#Drawings and folders

Body fields for POST /api/entities:

• type (required): "Drawing" or "Folder".
• name (required): up to 50 characters.
• width and height: canvas size in pixels, for drawings.
• background: canvas background color as hex, for example "#ffffff".
• Where to put it: project (a channel ID), and optionally folder (a folder ID inside that channel). If you leave these out, it goes into your personal files.

#More examples

#List your Artspaces and channels

Use this to find the teamId and projectId values you need for other calls.

curl https://magma.com/api/teams \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response (shortened):

{
  "hash": "a6323ff",
  "processingTime": 38,
  "statusCode": 200,
  "data": [
    {
      "_id": "66f1c2a9e4b0a1d2c3f40010",
      "name": "Moonlit Studio",
      "slug": "moonlit-studio",
      "isPublic": false,
      "projects": [
        {
          "_id": "66f1c2a9e4b0a1d2c3f40020",
          "name": "concept-art",
          "team": "66f1c2a9e4b0a1d2c3f40010",
          "type": "project",
          "shareType": 0
        }
      ]
    }
  ]
}

#Create a drawing in a channel

curl -X POST https://magma.com/api/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Drawing",
    "name": "Forest moodboard",
    "width": 1920,
    "height": 1080,
    "background": "#ffffff",
    "project": "66f1c2a9e4b0a1d2c3f40020"
  }'

The response's data is the new drawing, including its _id and shortId:

{
  "hash": "a6323ff",
  "processingTime": 95,
  "statusCode": 200,
  "data": {
    "_id": "66f1c2a9e4b0a1d2c3f40030",
    "shortId": "Xk3pQ9vT2m",
    "type": "Drawing",
    "name": "Forest moodboard",
    "team": "66f1c2a9e4b0a1d2c3f40010",
    "project": "66f1c2a9e4b0a1d2c3f40020"
  }
}

#Upload an image as a new drawing

POST /api/entities/import takes a multipart/form-data body with type (Drawing), name, file, and optionally project and folder. Image formats Magma recognizes include PNG, JPG and PSD.

curl -X POST https://magma.com/api/entities/import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -F "type=Drawing" \
  -F "name=Character sheet" \
  -F "project=66f1c2a9e4b0a1d2c3f40020" \
  -F "file=@character-sheet.psd"

Uploads count towards your storage (or the Artspace's storage, if you import into a channel).

#Errors

Note that an invalid or revoked key returns 403, not 401.

#Limits

• Rate limit: 60 requests per minute per user on the free plan, and 600 requests per minute on a paid plan. The limit is per user, not per key. When you go over it you get HTTP 429; wait a bit and retry with backoff.
• Names: drawing, folder and channel names can be up to 50 characters; Artspace names up to 32.

#Keep your key safe

• Your key can do everything your account can, in every Artspace you belong to. Never share it, commit it to a repository, or put it in a web page or app that other people can download.
• Store it in an environment variable or a secrets manager.
• If a key may have leaked, open Account & Billing > API and choose Refresh (to get a new key) or Remove (to revoke it). The old key stops working immediately.

#FAQ

Is the API available on the free plan? Yes. Free accounts need a verified email address and get 60 requests per minute. Paid plans get 600 requests per minute.

Can I create an API key for an Artspace instead of for my user? No. Keys are personal and act as you. Anything the key does shows up as done by your account.

Where do I find an Artspace or channel ID? Call GET /api/teams. Each Artspace's _id is its teamId, and each item in its projects list is a channel with its own _id.

I get 403 "Access denied" on every call. What's wrong? Check that the header is exactly Authorization: Bearer YOUR_API_KEY, that the key hasn't been refreshed or removed, and that your email address is verified. If only some calls fail, your account probably lacks the Artspace permission that action needs.

Can I post chat messages with the REST API? Not with an API key. To post into Artspace chat, create a webhook bot. See Artspace bots and chat webhooks.

Artspace bots and chat webhooks

Connect automated bots and services to Artspace chat: post messages through a webhook URL, and get signed events on your server when people write in your channels.

Webhooks let an automated bot take part in your Artspace's chat and create new experiences for your community. A bot can welcome new members, announce the theme of the week, run a drawing contest and count the votes, or track art levels and celebrate when someone levels up. Each webhook shows up in chat as its own sender, with a name, avatar and an optional BOT or APP badge.

#Who this is for

• Artspace admins who want to connect a tool to their channels.
• Community builders and developers creating an automated bot or integration for a Magma Artspace.

To automate drawings, channels or members instead of chat, see the Magma REST API.

#Two directions

A webhook can work in one or both directions. You choose this with the Capabilities checkboxes when you create it.

A two-way bot uses both: it receives a message at its callback URL, then replies through the webhook URL.

#Before you start

• You need the Manage artspace permission in the Artspace.
• Webhooks must be turned on for your Artspace. If you don't see a Webhooks tab in Artspace Settings, they're not available for your Artspace yet.
• If you want to receive messages, you need a server that is reachable over HTTPS. Plain http:// callback URLs are rejected.

#Step 1: Create a webhook

1. In the Artspace list on the left, right-click your Artspace's icon and choose Artspace Settings.
2. Open the Webhooks tab and click Create Webhook.
3. Fill in the form:
   • Display name: shown as the sender name in chat (up to 100 characters), for example "Contest Bot".
   • Avatar: upload an image, pick a random one, or remove it.
   • Badge: Bot, App or None. Shown next to the name in chat.
   • Scope: which channels the webhook can use (see the table below). For One channel or Specific channels, pick the channels from the list.
   • Capabilities: tick Can post messages, Receives channel messages, or both.
   • Callback URL: appears when you tick Receives channel messages. This is the HTTPS address on your server that Magma will POST to.
4. Click Create Webhook.
5. A Save these credentials now box appears with your Token and, if you set a callback URL, your signing Secret. Copy both and store them somewhere safe. They are shown only once.

The form also has a Usage guide section with ready-made examples for your settings.

#Your webhook URL

Your webhook URL is:

https://magma.com/api/hooks/chat/YOUR_TOKEN

You can copy the full URL later with the copy button next to the webhook in the Webhooks list.

#Scopes and channel names

In the API, a channel is identified by a name like project/66f1c2a9e4b0a1d2c3f40020, where the long part is the channel's ID. The channel picker in the webhook form shows this name under each channel, and every outgoing event includes it in the channel field.

#Step 2: Post a message (incoming)

There's no header to set: the token in the URL is the credential. Send JSON with Content-Type: application/json.

curl -X POST https://magma.com/api/hooks/chat/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "project/66f1c2a9e4b0a1d2c3f40020",
    "text": "Theme of the week: Ocean Creatures! Post your entry in #contest by Sunday."
  }'

For a webhook scoped to One channel, you can leave out channel:

curl -X POST https://magma.com/api/hooks/chat/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"text": "Voting is open! React with a star on your favourite entry."}'

Message fields:

Because text and content are both accepted, simple Slack-style ({"text": "..."}) and Discord-style ({"content": "..."}) payloads work.

About attachments: Magma downloads each image from its url, so the URL must be publicly reachable. Only images are accepted, up to 10 MB each. An attachment that can't be downloaded is skipped without an error, and the message is still posted.

A successful response contains the new message's ID in data.message_id:

{
  "hash": "a6323ff",
  "processingTime": 41,
  "statusCode": 200,
  "data": {
    "ok": true,
    "message_id": "6700a1b2c3d4e5f601234567"
  }
}

Keep the message_id if you want to edit the message later.

#More things your bot can do

All of these use the same webhook URL as a base. The ones that change chat (react, typing, edit) need Can post messages to be on.

Typing indicator. While your bot is working, send {"active": true} about every 10 seconds, then {"active": false} when it's done. If you stop sending, the indicator fades on its own.

Editing messages. Keep a live message up to date instead of posting a new one each time, for example a contest leaderboard or a vote count: post it once, then use PATCH …/messages/{messageId} to update it. A webhook can only edit its own messages.

Reading history. GET …/messages returns the most recent messages in the channel, newest first, up to 20 per call. To page back, pass before with the timestamp of the oldest message you already have (an ISO 8601 date). Each message includes id, channel, user_id, user (id, name, username, avatar, is_bot), text, timestamp, edited, and thread and reply_to when they apply.

curl "https://magma.com/api/hooks/chat/YOUR_TOKEN/messages?channel=project/66f1c2a9e4b0a1d2c3f40020&limit=10"

#Step 3: Receive messages (outgoing)

If Receives channel messages is on, Magma sends a POST with a JSON body to your callback URL for every new message and reaction in the channels the webhook covers.

• Your bot is not sent its own messages or reactions. It does receive messages from other bots.
• Deleted messages are not sent.
• Only Artspace channels are covered, not direct messages.

#Event: new message

{
  "kind": "message",
  "text": "@levelbot what level am I?",
  "channel": "project/66f1c2a9e4b0a1d2c3f40020",
  "user_id": "66f1c2a9e4b0a1d2c3f40001",
  "message_id": "6700a1b2c3d4e5f601234568",
  "timestamp": "2026-09-23T14:05:12.000Z"
}

Optional fields:

• reply_to: the ID of the message this one replies to.
• thread: set when the message is in a thread, for example "thread/6700a1b2c3d4e5f601234599".
• uploads: files attached to the message, each with id, name, mimeType, size and url. The url is a signed download link that works for 1 hour; just GET it.

To get the sender's name and avatar, call GET …/users/{user_id} with your webhook URL.

#Event: reaction added or removed

{
  "kind": "reaction.add",
  "channel": "project/66f1c2a9e4b0a1d2c3f40020",
  "message_id": "6700a1b2c3d4e5f601234568",
  "user_id": "66f1c2a9e4b0a1d2c3f40001",
  "emoji": "👍",
  "timestamp": "2026-09-23T14:06:40.000Z"
}

When a reaction is removed, kind is "reaction.remove".

#Delivery

• Magma waits up to 10 seconds for your server. Reply quickly (for example with 200) and do slow work in the background.
• Delivery is attempted once. Failed deliveries are not retried, so make sure your endpoint is up.

#Verify the signature

Every outgoing request has an X-Webhook-Signature header. It's the HMAC-SHA256 of the raw request body, using your webhook's signing secret as the key, written as lowercase hex. Compute the same value from the raw body (before parsing the JSON) and compare. Reject the request if they don't match.

Node.js:

const crypto = require('crypto');

function isFromMagma(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(signatureHeader || '', 'hex');
  const b = Buffer.from(expected, 'hex');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Python:

import hmac, hashlib

def is_from_magma(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

#Test your callback

In the Webhooks list, open the gear menu next to your webhook and choose Test callback. Magma sends this signed test payload and tells you what status code your server returned:

{
  "text": "Test message from Magma webhook",
  "channel": "project/66f1c2a9e4b0a1d2c3f40020",
  "user_id": "system",
  "message_id": "test",
  "timestamp": "2026-09-23T14:00:00.000Z",
  "test": true
}

Test events have "test": true and no kind field. Ignore them in your bot logic.

#Errors

Error responses have the shape {"ok": false, "error": "..."}, with a status code you can use for retry logic:

#Limits

Rate limits apply per webhook, per action:

Other limits: messages up to 2,500 characters; up to 5 image attachments of 10 MB each; up to 50 channels for Specific channels; an Artspace can create up to 20 webhooks per hour.

#Security

• The token is the password. Anyone with your webhook URL can post into your channels as the bot and read recent messages in the channels it covers. Keep it out of public repositories, client-side code and screenshots.
• Rotate the token from the gear menu: Regenerate token. The old URL stops working immediately, so update your integration with the new one.
• Pause a webhook by unticking its Enabled checkbox in the list. Requests to its URL then fail with 401.
• Always verify X-Webhook-Signature on your callback endpoint, so nobody else can send fake events to your server.
• To replace the signing secret, delete the webhook and create a new one. There's no separate "regenerate secret" option.
• Delete a webhook from the gear menu when you no longer need it. Any integration using its URL stops working.

#FAQ

Which channels can a bot post to? Channels inside the Artspace that owns the webhook, within the scope you chose. Webhooks can't send direct messages or post in other Artspaces.

How do I find a channel's ID? The channel picker in the webhook form shows each channel's full name (project/…). Every outgoing event also includes it in channel. You can also list channels with the REST API (GET /api/teams).

Can I change the bot's name or avatar per message? No. Messages always use the webhook's display name and avatar. To change them, edit the webhook in Artspace Settings > Webhooks.

I lost my token. What now? Copy the full webhook URL with the copy button in the Webhooks list, or use Regenerate token to get a new one.

I lost my signing secret. What now? The secret is shown only once. Delete the webhook and create a new one to get a new secret.

My callback isn't getting anything. Check that Receives channel messages is ticked, the webhook is Enabled, the callback URL uses HTTPS and is publicly reachable, and the message was posted in a channel within the webhook's scope. Use Test callback to see what your server returns.

Can I manage webhooks through the REST API? Yes. With a personal API key from an account that has the Manage artspace permission, you can list, create, update and delete webhooks, regenerate tokens and send a test callback. See the reference below.

#Reference: managing webhooks with the REST API

These endpoints use your personal API key (Authorization: Bearer YOUR_API_KEY, see the REST API article) and need the Manage artspace permission. Successful responses are wrapped in the standard envelope, with the result in data.

Create and update body fields: name (required on create, up to 100 characters), scope (required on create: "team" for All channels, "channel" for One channel, or "channels" for Specific channels), channelNames (array of channel names; exactly one for "channel"), canReceive (Can post messages), canSend (Receives channel messages), callbackUrl (HTTPS; required when canSend is true), badge ("bot" or "app").

curl -X POST https://magma.com/api/teams/66f1c2a9e4b0a1d2c3f40010/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Art Bot",
    "scope": "channel",
    "channelNames": ["project/66f1c2a9e4b0a1d2c3f40020"],
    "canReceive": true,
    "canSend": true,
    "callbackUrl": "https://bots.example.com/magma/callback",
    "badge": "bot"
  }'