API Overview

The Spedy API lets you programmatically manage boards, tickets, users, and everything else in your organization. It follows REST conventions and returns JSON for all responses.

Base URL

All API requests are scoped to your organization's subdomain:

https://{org-slug}.spedy.ai/api/v1

Replace {org-slug} with your organization's slug (for example, acme-corp).

Authentication

All API requests must be authenticated using a Personal Access Token (PAT). Create a PAT from your account settings in the Spedy UI. PATs don't expire unless you revoke them, making them ideal for scripts, CI/CD pipelines, and long-lived integrations.

Include your token in the Authorization header of every request:

Authorization: Bearer spedy_pat_abc123...

PATs inherit the permissions of the user who created them. See the Authentication page for details on creating and managing tokens.

Request Format

• Send request bodies as JSON with the Content-Type: application/json header.
• File uploads use multipart/form-data instead.
• Query parameters use standard URL encoding.

Available API Sections

Pagination

List endpoints return paginated results. Use page and limit query parameters to control the window:

Paginated responses follow this shape:

{
  "data": [],
  "total": 142,
  "page": 1,
  "pageSize": 20,
  "totalPages": 8
}

Error Handling

When something goes wrong, the API returns a consistent error object:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Common status codes:

Rate Limiting

Certain endpoints have rate limits to protect the platform. When you exceed a limit, you'll receive a 429 response. Rate limits are applied per token and vary by endpoint.

Multi-Tenancy

Spedy is a multi-tenant platform. Every resource belongs to an organization, and all API responses are automatically scoped to the organization of the authenticated user. You cannot access resources from other organizations.

Soft Deletes

Most resources use soft deletion. Deleted items are excluded from list responses by default but may be included with an includeDeleted query parameter where supported. Soft-deleted resources retain their IDs and can sometimes be restored.

Permissions

Access control is enforced at two levels:

1. Organization role -- Admin, TeamMember, or Customer. Admins have full access; customers have restricted visibility (e.g. no secret comments).
2. Feature permissions -- granular capabilities like tickets:edit, milestones:view, or time-tracking:manage. These are checked per-endpoint and documented on each resource page.

Some features (Teams, Webhook Endpoints) require a Pro plan subscription.

Feature Guards

Certain endpoints are gated behind board-level feature flags. For example, milestones and releases require the Milestones & Releases feature to be enabled on the board, and time tracking requires the Time Tracking feature to be enabled for the organization. If a feature is not enabled, requests to those endpoints return 403 Forbidden.