Open this in Magpie

API access requires Pro.

Create a key

  1. Open API keys in Account settings, under Sign-in and security, or type API keys in ⌘K.
  2. Select Create key.
  3. On the New API key page, name the key after the program that will use it.
  4. Choose what it can reach, its team and when it expires.
  5. Select Create key.

The full secret is shown once, and Magpie cannot show it again. Keep it in Password Vault (below), another password manager or a secret store. Revoking a key stops it immediately.

Creating a key needs a sign-in in the last 10 minutes. After an older one, Magpie asks you to confirm it's you first and then brings you back to the New API key page, with what you chose kept; in the Magpie app, it asks for your password or a two-factor code. Magpie emails you each time a key is made for your account, so a key you did not make can be revoked from the link in that email. A key keeps working after you change your password or sign out of every other browser, so revoke it on this page when it should stop. If the New API key page was open while you signed out and in again, Create key makes nothing and opens the page again with what you chose; select Create key once more.

Save a new key in Password Vault

Save in Password Vault is beside a new key when you have set up Password Vault.

  1. Select Save in Password Vault. Password Vault opens in a new tab.
  2. Unlock Password Vault if it asks. A new API credential opens, filled in.
  3. Select Save.

The credential is named after the key. Its notes give Magpie's address, what the key can reach, its team and when it expires.

The key is encrypted in your browser before it is stored, as everything in Password Vault is.

What a key can reach

What the key can reach starts with nothing chosen. Every area lets the key read and change everything the API covers, including areas added later. Only the areas I choose lists every area under the homepage's groups, with Find an area to narrow them by name; for each, choose None, Read or Read and write. A request outside the key's areas, or a change in an area it only reads, answers 403 forbidden_scope; Search, Dashboard, Trash and the account's own routes need Every area. Team pins the key to one of your teams, Personal included, and it then works only there. Expires stops the key in 1 hour, 1 day, 30 days or 1 year, never, or at a date and time you choose, to the second, in the time zone of your Account settings. An expired key answers 401 api_key_expired. None of these can be changed after the key is created; make a new key instead.

Your keys

The API keys page lists each key with what it can reach, its team, when it expires or that it has expired, and when it was last used. An expired key stays listed until you revoke it. A key made by another key through the API says which key made it, and stops working when that key is revoked or expires, so revoking a key also stops the keys it made.

Use the API

Send the key in every request:

Authorization: Bearer YOUR_SECRET_KEY

The base path is /api/v1. The API provides list, create, read, update, confirm, cancel, archive, and delete operations for bookings as applicable; create and management operations for event types and availability; issue list, read, create and update operations; the signed-in user record; and webhook subscriptions. Store orders, Products, stock, returns, customers and Store webhooks have their own routes, described in Store API and webhooks. The API reference describes bookings, event types, availability, the user record, webhooks and Store, with their fields, statuses and errors. Download OpenAPI 3.0 Spec on that page gives the OpenAPI file, which lists every route, including Notes, Documents, Contacts, Invoices, To-dos, Calendar and the other areas the Magpie app uses. A key acts as the person who created it, with their access.

To use Magpie from Claude, ChatGPT, Cursor or another app that connects to tools, see Connected apps. An API key can be sent to https://magpie.diy/mcp in the same Authorization: Bearer header.

Issue routes use the selected Personal or team context. An API key follows the website's current team; send X-Magpie-Team-Id to select another team the key's owner can view. A key pinned to a team always uses that team. Issue list results come a page at a time. Filter by status key, priority, project UUID, assignee user ID, or search text:

GET /api/v1/issues?project=PROJECT_UUID&status=in_progress&page=1

Read one issue with GET /api/v1/issues/ISSUE_UUID. Create an issue with a title and optional Markdown description and project UUID:

{
  "title": "Review the export flow",
  "description_markdown": "Check the downloaded CSV.",
  "project_uuid": "PROJECT_UUID"
}

API-created issues enter the selected team's Triage queue (see Triage and public issue forms). Issues created in the Magpie app go straight into the team's workflow, as on the website. Update an issue with PATCH /api/v1/issues/ISSUE_UUID; supported fields are title, description_markdown, status, priority, assignee_user_id and due_date; the OpenAPI file gives each field's maximum length. Use null to clear an assignee or due date. Issue writes require edit access to the selected team. DELETE /api/v1/issues/ISSUE_UUID moves an issue to Trash, where it can be restored for 30 days. Use GET /api/v1/issues/trash to list issues in the selected team's Trash and POST /api/v1/issues/ISSUE_UUID/restore to restore one before its restore_until time. Delete and restore require team edit access. Issues in Trash no longer appear in the ordinary issue list or detail route.

Several programs can share one backlog safely. Every issue carries an etag, also sent as the ETag header when you read one. Send it back as If-Match when you update the issue, and the update is made only if nobody changed the issue since you read it; otherwise the API answers 412 and changes nothing, so read the issue again. To take an issue, update its status and set yourself as assignee with If-Match: if two programs try at once, only one succeeds. List what is free with assignee=none, and sort by a Number field with sort=field:FIELD_UUID (lowest first) or sort=-field:FIELD_UUID (highest first); issues without a value come last.

To retry creating an issue or a comment without making it twice, send an Idempotency-Key header with a value you choose, such as a UUID. A retry with the same key and the same request within 24 hours gets the first answer back, marked Idempotent-Replayed: true.

Other requests that email or text someone, or record money, take the same header: sending your meeting page, invitations, invoices and their payments, expenses, replies in Helpdesk, E-Signatures, Hiring, Coaching, Appointments and Store orders, among others. The API reference marks each one. For a file upload, send a new key with each file.

GET /api/v1/issues/options returns the selected team's statuses in workflow order, priorities, assignable members and projects, and whether you can edit issues there. GET /api/v1/issues/ISSUE_UUID/comments lists an issue's comments, oldest first, and POST to the same address with body_markdown adds one.

GET /api/v1/trash lists the selected team's Trash as the website shows it to the key's owner: a page at a time, newest first, each with its uuid, title, label, area, who moved it, moved_at, restore_until, can_restore and can_delete_forever, and areas with a count for each area. Narrow it with area (such as notes or issues), q and page. POST /api/v1/trash/ENTRY_UUID/restore restores an entry and DELETE /api/v1/trash/ENTRY_UUID deletes it forever; ENTRY_UUID is the entry's own uuid, not the note's or document's. A restore past restore_until answers 410 with restore_window_expired, and one that would go over a plan limit answers 409 with plan_limit. The DELETE routes of notes, documents, presentations, Designs, Idea Boards, forms and screen recordings move them to Trash and answer with restore_until.

Webhook deliveries include X-Magpie-Event, X-Magpie-Id, X-Magpie-Timestamp, and X-Magpie-Signature. Verify the timestamp and HMAC signature before processing the body. Store the delivery ID so a retry is not applied twice.

Repeated requests carrying a key the API rejects are limited. After about twenty, the API answers 429 with a Retry-After header giving the number of seconds to wait; a request that authenticates clears the count. Check which key the integration sends, and whether it was revoked, before retrying.

Never put a secret key in browser JavaScript, a public repository, or a URL. If a key may have been exposed, revoke it and make another. For an API response or signature that does not match the reference, Contact support.

Ask Magpie support

Send Magpie staff a question about anything this article does not answer.