API v1 MCP OpenAPI

REST · JSON · OpenAPI

Build on Backlog.pm

Read and change spaces, issues, sprints, roadmaps, documentation and support requests from your own tools. Every request acts as you, with your role’s permissions.

BASE URL /api/v1
Endpoints
–
Groups
–
Auth
Bearer
Format
JSON

Quick start

From nothing to your first response in three steps.

  1. 01

    Create a token

    In Backlog.pm, open Account settings → Integrations → API credentials and generate a token. It starts with bpm_pat_ and is shown once, so keep it somewhere safe.

  2. 02

    Send it with every request

    Put it in the Authorization header as Bearer bpm_pat_…. Your workspace comes from the address, so use your own {workspace}.backlog.pm.

  3. 03

    Try any endpoint below

    Press Authorize, paste the token, then Try it out on an endpoint. Requests run against the workspace this page is open on.

200 OK application/json · your spaces, as a list

Good to know

Permissions

A token acts as its owner with their current role. API tokens work on /api/v1, MCP tokens only on /mcp. A few settings (tokens, AI keys, workspace deletion) need a signed-in session and answer 403 session_required.

Requests

Bodies are JSON only (anything else is 415) and at most 4 MB; uploads have their own limits. Ids are UUIDs, dates are YYYY-MM-DD, times are RFC 3339.

Errors

Every error has the same shape, with a stable code to switch on:

{ "error": { "code": "validation_failed",
  "message": "Some fields need attention.",
  "fields": { "title": "title_required" } } }

Statuses

An issue is todo, progress, done or cancelled. In progress is one of the team’s working statuses: board_column_id says which, status_name what it’s called.

Endpoints

Grouped by what they work on. Open one to see its parameters, its responses and an example.

Loading the reference…