API keys and REST API

API access requires Pro. Open API keys, select Create key, name the key after the program that will use it, and create it. The full secret is shown once. Store it in a password manager or secret store; Magpie cannot show it again. Revoking a key stops it immediately.

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. Open /docs/api for the complete resource, field, status, and error reference before building a client.

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. Issue list results contain up to 100 records per page. 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. 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 (up to 100,000 characters), status, priority, assignee_user_id and due_date. 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; it is recoverable for 30 days. Use GET /api/v1/issues/trash to list issues in the selected team and POST /api/v1/issues/ISSUE_UUID/restore to restore one before its restore_until time. Delete and restore require team edit access. Trashed issues no longer appear in the ordinary issue list or detail route.

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.

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. A client that keeps sending a revoked key is the usual cause, so check which key the integration is configured with 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.