API Reference

Complete reference for the Planet Roadmap REST API. All endpoints are scoped to a single organization and authenticated with an API key. Generated from the OpenAPI 3.0 spec.

Base URL

https://planetroadmap.com/api/v1/{orgSlug}

Authentication

Authorization: Bearer pk_live_...

Download OpenAPI spec Authentication guide

Try it: Verify your key

The whoami endpoint is the easiest way to confirm your API key works and inspect its scopes. Replace your-org and pk_live_your_key.

cURL

curl https://planetroadmap.com/api/v1/your-org/whoami \
  -H "Authorization: Bearer pk_live_your_api_key"

Need a key? Generate one in your organization settings (replace your-org with your slug). API access requires a Pro or Enterprise plan.

Scopes

API keys are granted explicit scopes when created. A request that requires a scope not granted to the key will return 403 forbidden.

Scope	Grants
`tasks:read`	List tasks.
`tasks:write`	Create tasks.
`projects:read`	List projects.
`okrs:read`	List OKRs and key results.
`okrs:write`	Create/update OKRs (reserved).
`roadmap:read`	List roadmap items.
`roadmap:write`	Create roadmap items.
`requests:read`	List feature requests.
`requests:write`	Create feature requests.
`comments:read`	List feature request comments.
`comments:write`	Create feature request comments.
`signals:read`	Read activity signals (used by integrations).
`signals:write`	Send activity signals from git hooks/CI.

Endpoints

Whoami — 1 operation
Tasks — 2 operations
Projects — 1 operation
OKRs — 1 operation
Roadmap — 2 operations
Requests — 2 operations
Comments — 2 operations

Whoami

Verify your API key and inspect granted permissions.

get/api/v1/{orgSlug}/whoami

Verify API key

Returns the organization the API key belongs to and the permissions it has been granted. Useful for debugging key configuration.

Parameters

Name	In	Type	Description
`orgSlug`required	`path`	`string`	Your organization slug. Must match the org the API key was issued for.

Responses

200API key information.
401Missing or invalid Authorization header / API key.
403API key lacks required permission, organization mismatch, or plan does not include API access.
429Rate limit exceeded (100 requests per minute per API key).
500Unexpected server error.

Show success response schema

Field	Type	Description
`data`required	`Whoami`

Tasks

Internal tasks belonging to projects.

get/api/v1/{orgSlug}/tasks

List tasks

List tasks in your organization. Requires `tasks:read` permission.

Parameters

Name	In	Type	Description
`orgSlug`required	`path`	`string`	Your organization slug. Must match the org the API key was issued for.
`status`	`query`	`enum: "todo" \| "in_progress" \| "in_review" \| "done" \| "blocked"`	Filter by task status.
`projectId`	`query`	`string`	Filter to tasks in a specific project.
`assigneeId`	`query`	`string`	Filter to tasks assigned to a specific user id.
`search`	`query`	`string`	Case-insensitive substring match on title/description.
`since`	`query`	`string (date-time)`	Only return items created/updated after this ISO 8601 timestamp.
`limit`	`query`	`integer`	Maximum number of items to return (1-100).Default: `20`
`offset`	`query`	`integer`	Number of items to skip for pagination.Default: `0`
`sort`	`query`	`enum: "newest" \| "oldest"`	Sort order. Defaults to 'newest'.Default: `"newest"`

Responses

200Paginated list of tasks.
400Request validation failed (missing required field, invalid enum value, etc.).
401Missing or invalid Authorization header / API key.
403API key lacks required permission, organization mismatch, or plan does not include API access.
429Rate limit exceeded (100 requests per minute per API key).
500Unexpected server error.

Show success response schema

Field	Type	Description
`data`required	`Task[]`
`meta`	`object`

post/api/v1/{orgSlug}/tasks

Create task

Create a new task. Requires `tasks:write` permission.

Parameters

Name	In	Type	Description
`orgSlug`required	`path`	`string`	Your organization slug. Must match the org the API key was issued for.

Request Body

Field	Type	Description
`title`required	`string`	Required. Non-empty.
`description`	`string \| null`
`projectId`	`string \| null`	Must belong to your org.
`status`	`enum: "todo" \| "in_progress" \| "in_review" \| "done" \| "blocked"`	Default: `"todo"`
`priority`	`enum: "low" \| "medium" \| "high" \| "urgent"`	Default: `"medium"`
`assigneeEmail`	`string`	Email of an org member to assign. Must already be a member.
`startDate`	`string (date-time)`
`dueDate`	`string (date-time)`

Example

{
  "title": "Write API docs",
  "description": "Document the v1 endpoints",
  "status": "todo",
  "priority": "medium",
  "assigneeEmail": "alex@example.com",
  "dueDate": "2026-06-01T00:00:00Z"
}

Responses

201Task created.
400Request validation failed (missing required field, invalid enum value, etc.).
401Missing or invalid Authorization header / API key.
403API key lacks required permission, organization mismatch, or plan does not include API access.
404Resource not found within this organization.
429Rate limit exceeded (100 requests per minute per API key).
500Unexpected server error.

Show success response schema

Field	Type	Description
`data`required	`Task`

Projects

Projects within your organization.

get/api/v1/{orgSlug}/projects

List projects

List projects in your organization. Requires `projects:read` permission.

Parameters

Name	In	Type	Description
`orgSlug`required	`path`	`string`	Your organization slug. Must match the org the API key was issued for.
`status`	`query`	`enum: "active" \| "on_hold" \| "completed" \| "cancelled"`	Filter by project status.
`search`	`query`	`string`	Case-insensitive substring match on title/description.
`limit`	`query`	`integer`	Maximum number of items to return (1-100).Default: `20`
`offset`	`query`	`integer`	Number of items to skip for pagination.Default: `0`
`sort`	`query`	`enum: "newest" \| "oldest"`	Sort order. Defaults to 'newest'.Default: `"newest"`

Responses

200Paginated list of projects.
400Request validation failed (missing required field, invalid enum value, etc.).
401Missing or invalid Authorization header / API key.
403API key lacks required permission, organization mismatch, or plan does not include API access.
429Rate limit exceeded (100 requests per minute per API key).
500Unexpected server error.

Show success response schema

Field	Type	Description
`data`required	`Project[]`
`meta`	`object`

OKRs

Objectives and key results.

get/api/v1/{orgSlug}/okrs

List OKRs

List objectives with their key results and computed progress. Requires `okrs:read` permission.

Parameters

Name	In	Type	Description
`orgSlug`required	`path`	`string`	Your organization slug. Must match the org the API key was issued for.
`period`	`query`	`string`	Filter by period (substring match), e.g. `2026-Q1`.
`status`	`query`	`enum: "on_track" \| "at_risk" \| "behind" \| "achieved"`	Filter by objective status.
`since`	`query`	`string (date-time)`	Only return items created/updated after this ISO 8601 timestamp.
`limit`	`query`	`integer`	Maximum number of items to return (1-100).Default: `20`
`offset`	`query`	`integer`	Number of items to skip for pagination.Default: `0`
`sort`	`query`	`enum: "newest" \| "oldest"`	Sort order. Defaults to 'newest'.Default: `"newest"`

Responses

200Paginated list of OKRs.
400Request validation failed (missing required field, invalid enum value, etc.).
401Missing or invalid Authorization header / API key.
403API key lacks required permission, organization mismatch, or plan does not include API access.
429Rate limit exceeded (100 requests per minute per API key).
500Unexpected server error.

Show success response schema

Field	Type	Description
`data`required	`OKR[]`
`meta`	`object`

Roadmap

Tasks viewed as roadmap items.

get/api/v1/{orgSlug}/roadmap

List roadmap items

List tasks viewed as roadmap items. Requires `roadmap:read` permission.

Parameters

Name	In	Type	Description
`orgSlug`required	`path`	`string`	Your organization slug. Must match the org the API key was issued for.
`status`	`query`	`string`	Filter by status (any task status string).
`priority`	`query`	`enum: "low" \| "medium" \| "high" \| "urgent"`	Filter by priority.
`limit`	`query`	`integer`	Maximum number of items to return (1-100).Default: `20`
`offset`	`query`	`integer`	Number of items to skip for pagination.Default: `0`
`sort`	`query`	`enum: "newest" \| "oldest"`	Sort order. Defaults to 'newest'.Default: `"newest"`

Responses

200Paginated list of roadmap items.
401Missing or invalid Authorization header / API key.
403API key lacks required permission, organization mismatch, or plan does not include API access.
429Rate limit exceeded (100 requests per minute per API key).
500Unexpected server error.

Show success response schema

Field	Type	Description
`data`required	`Task[]`
`meta`	`object`

post/api/v1/{orgSlug}/roadmap

Create roadmap item

Create a new roadmap item (stored as a task). Requires `roadmap:write` permission.

Parameters

Name	In	Type	Description
`orgSlug`required	`path`	`string`	Your organization slug. Must match the org the API key was issued for.

Request Body

Field	Type	Description
`title`required	`string`	Required. Non-empty.
`description`	`string \| null`
`status`	`string`	Default: `"todo"`
`priority`	`string`	Default: `"medium"`
`projectId`	`string \| null`

Example

{
  "title": "Ship dark mode",
  "description": "High priority for Q2",
  "status": "todo",
  "priority": "high"
}

Responses

201Roadmap item created.
400Request validation failed (missing required field, invalid enum value, etc.).
401Missing or invalid Authorization header / API key.
403API key lacks required permission, organization mismatch, or plan does not include API access.
429Rate limit exceeded (100 requests per minute per API key).
500Unexpected server error.

Show success response schema

Field	Type	Description
`data`required	`Task`

Requests

Public-facing feature requests on portals.

get/api/v1/{orgSlug}/requests

List feature requests

List feature requests across all portals in your organization. Requires `requests:read` permission.

Parameters

Name	In	Type	Description
`orgSlug`required	`path`	`string`	Your organization slug. Must match the org the API key was issued for.
`status`	`query`	`string`	Filter by feature request status.
`search`	`query`	`string`	Case-insensitive substring match on title/description.
`since`	`query`	`string (date-time)`	Only return items created/updated after this ISO 8601 timestamp.
`sort`	`query`	`enum: "newest" \| "oldest" \| "votes"`	Sort order.Default: `"newest"`
`limit`	`query`	`integer`	Default: `20`
`offset`	`query`	`integer`	Default: `0`

Responses

200Paginated list of feature requests.
401Missing or invalid Authorization header / API key.
403API key lacks required permission, organization mismatch, or plan does not include API access.
429Rate limit exceeded (100 requests per minute per API key).
500Unexpected server error.

Show success response schema

Field	Type	Description
`data`required	`FeatureRequest[]`
`meta`	`object`

post/api/v1/{orgSlug}/requests

Create feature request

Create a feature request on a portal. If `portalSlug` is omitted, the org's first portal is used. Requires `requests:write` permission.

Parameters

Name	In	Type	Description
`orgSlug`required	`path`	`string`	Your organization slug. Must match the org the API key was issued for.

Request Body

Field	Type	Description
`title`required	`string`	Required. Non-empty.
`description`	`string \| null`
`status`	`enum: "open" \| "under_review" \| "planned" \| "in_progress" \| "completed" \| "declined"`	Default: `"open"`
`categoryId`	`string \| null`
`portalSlug`	`string`	Portal slug to post to. If omitted, uses the org's first portal.

Example

{
  "title": "Add dark mode",
  "description": "Customers asking for a dark theme",
  "status": "open",
  "portalSlug": "main"
}

Responses

201Feature request created.
400Request validation failed (missing required field, invalid enum value, etc.).
401Missing or invalid Authorization header / API key.
403API key lacks required permission, organization mismatch, or plan does not include API access.
404Resource not found within this organization.
429Rate limit exceeded (100 requests per minute per API key).
500Unexpected server error.

Show success response schema

Field	Type	Description
`data`required	`FeatureRequest`

Comments

Comments on feature requests.

get/api/v1/{orgSlug}/comments

List comments

List comments on feature requests in your organization. Requires `comments:read` permission.

Parameters

Name	In	Type	Description
`orgSlug`required	`path`	`string`	Your organization slug. Must match the org the API key was issued for.
`featureRequestId`	`query`	`string`	Filter to comments for a specific feature request.
`since`	`query`	`string (date-time)`	Only return items created/updated after this ISO 8601 timestamp.
`limit`	`query`	`integer`	Maximum number of items to return (1-100).Default: `20`
`offset`	`query`	`integer`	Number of items to skip for pagination.Default: `0`
`sort`	`query`	`enum: "newest" \| "oldest"`	Sort order. Defaults to 'newest'.Default: `"newest"`

Responses

200Paginated list of comments.
401Missing or invalid Authorization header / API key.
403API key lacks required permission, organization mismatch, or plan does not include API access.
429Rate limit exceeded (100 requests per minute per API key).
500Unexpected server error.

Show success response schema

Field	Type	Description
`data`required	`Comment[]`
`meta`	`object`

post/api/v1/{orgSlug}/comments

Create comment

Create a comment on a feature request. API-created comments default to `isOfficial: true`. Requires `comments:write` permission.

Parameters

Name	In	Type	Description
`orgSlug`required	`path`	`string`	Your organization slug. Must match the org the API key was issued for.

Request Body

Field	Type	Description
`featureRequestId`required	`string`	Required. Must belong to your org.
`body`required	`string`	Required. Non-empty.
`isOfficial`	`boolean`	API-created comments default to official.Default: `true`

Example

{
  "featureRequestId": "fr_abc123",
  "body": "Thanks for the suggestion — shipping next sprint.",
  "isOfficial": true
}

Responses

201Comment created.
400Request validation failed (missing required field, invalid enum value, etc.).
401Missing or invalid Authorization header / API key.
403API key lacks required permission, organization mismatch, or plan does not include API access.
404Resource not found within this organization.
429Rate limit exceeded (100 requests per minute per API key).
500Unexpected server error.

Show success response schema

Field	Type	Description
`data`required	`Comment`

Error format

All error responses follow a consistent shape:

Error

{
  "error": {
    "code": "validation_error",
    "message": "Title is required and must be a non-empty string"
  }
}

See Errors for the full list of error codes and Rate Limits for throttling details.