Spedy Docs

Everything you need to integrate with the Spedy API -- authentication, request format, pagination, and error handling.

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

Every request must include a valid access token. Spedy supports two authentication methods:

Bearer Token (JWT)

Obtain a token by calling the login endpoint with your email and password. Then include it in every request:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

JWTs expire after a short period. Use the refresh endpoint to get a new one without re-entering credentials.

Personal Access Tokens (PAT)

For scripts, CI/CD pipelines, and long-lived integrations, create a Personal Access Token from your account settings. PATs don't expire unless you revoke them. Include them the same way:

Authorization: Bearer spedy_pat_abc123...

See the Authentication page for full details on both methods.

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.

Pagination

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

Parameter	Type	Default	Description
page	number	1	Page number (starts at 1)
limit	number	20	Items per page (max 100)

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:

Code	Meaning
400	Bad Request -- invalid input or constraint violation
401	Unauthorized -- missing or invalid token
403	Forbidden -- insufficient permissions
404	Not Found -- resource doesn't exist or isn't accessible
409	Conflict -- duplicate name or invalid state transition
429	Too Many Requests -- rate limit exceeded

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 IP address and vary by endpoint -- for example, login attempts are more strictly limited than read operations.

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.

API Overview