JSON:API Overview

Catalio exposes a JSON:API-compatible REST surface (jsonapi.org). We describe the JSON:API resource/relationship/error shape without pinning a 1.0 vs 1.1 version label — use the interactive docs below as the source of truth for complete endpoint details, schemas, and live testing.

Interactive Documentation

Start here: The Swagger UI is the best way to explore the API.

Using Swagger UI:

1. Navigate to /api/swaggerui
2. Click Authorize and enter: Bearer YOUR_TOKEN_HERE
3. Browse resources, expand operations, and click Try it out

Authentication

All endpoints require Bearer token authentication. See the Authentication Guide for token management.

curl /api/v1/requirements \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Accept: application/vnd.api+json"

Available Resources

These resources are also available, with the same CRUD routes:

All resources above support standard CRUD: GET (list/show), POST (create), PATCH (update), DELETE.

Initiative-scoped resources — /api/v1/initiative-questions, /api/v1/initiative-decisions, /api/v1/capability-assessments, /api/v1/initiative-scope, and /api/v1/change-proposals — list records for one initiative at a time, so their list routes require an initiative ID. Change proposals can also be listed per application; see the API Endpoint Reference for those routes. Check the Swagger UI for each route’s parameters and supported operations.

Quick Reference

Filtering, Sorting & Pagination

# Filter by field
GET /api/v1/requirements?filter[status]=active

# Sort (prefix - for descending)
GET /api/v1/requirements?sort=-updated_at

# Include relationships
GET /api/v1/requirements?include=personas,use_cases

# Combine filter, sort, and include
GET /api/v1/requirements?filter[status]=active&sort=-priority&include=personas

Pagination

The /requirements, /personas, /use-cases, and /initiatives list routes are paginated. Most other list routes (TestCase, TestResult, Component, Process, Policy, Capability, Team) are not, and return the full result set.

On a paginated route, leaving out page[*] returns the first 25 records, not the whole collection:

• page[limit] sets the page size (default 25). /requirements caps a page at 50.
• page[offset] pages by offset.
• page[after] / page[before] page by cursor, using the cursors returned in links.

GET /api/v1/requirements?page[limit]=20&page[offset]=40

To read every record, follow the links.next URL until it is empty. Cursor paging stays stable when records are added while you page; offset paging can skip or repeat rows.

Treat cursors as opaque: use the value the API returned, and don’t build or parse your own. A cursor belongs to the sort order it was issued under, so changing sort invalidates it. An invalid cursor returns 400 with an error code of invalid_keyset. page[size] and page[number] are not supported and are ignored.

Create Example

curl -X POST /api/v1/requirements \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "Requirement",
      "attributes": {
        "title": "OAuth2 Authentication",
        "user_want": "authenticate using OAuth2",
        "user_benefit": "secure passwordless access",
        "personas": [{"id": "<persona-uuid>"}]
      }
    }
  }'

Common Status Codes

Multi-Tenant Security

All requests are automatically scoped to your organization based on your authentication token. Cross-tenant access returns 404 (not 403) for security.

Next Steps

• API Authentication — Create credentials and obtain access tokens
• API Endpoint Reference — Change proposals by application, use case and test case payloads, CI test-run uploads, and /api/v2/context
• MCP Authentication — Connect AI agents over OAuth2 (no API key)
• Driving Catalio from Your IDE over MCP — Workflow after MCP sign-in
• Swagger UI — Explore and test endpoints interactively