API Guides 3 min read

JSON:API Overview

Getting started with Catalio's JSON:API - authentication, endpoints, and interactive documentation.

Updated
On this page

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.

Resource Description
Swagger UI Interactive API explorer with live testing
OpenAPI Spec Download for client generation or import tools
Bruno Collection Pre-built API collection for Bruno REST client

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.

Bash 
curl /api/v1/requirements \

  -H "Authorization: Bearer ${TOKEN}" \

  -H "Accept: application/vnd.api+json"
Header Value Required For
Authorization Bearer {token} All requests
Content-Type application/vnd.api+json POST/PATCH
Accept application/vnd.api+json All requests

Available Resources

Resource Endpoint Description
Requirement /api/v1/requirements Business requirements with AI-powered analysis
Persona /api/v1/personas User personas and stakeholder roles
UseCase /api/v1/use-cases Acceptance criteria and behavioral specifications
TestCase /api/v1/test-cases Test scenarios with steps and expected results
TestResult /api/v1/test-results Test execution records and results
Component /api/v1/components System components and architectural modules
Process /api/v1/processes Business processes and workflows
Policy /api/v1/policies Governance policies and compliance requirements
Capability /api/v1/capabilities Business capabilities for capability-based planning
Team /api/v1/teams Organizational units responsible for requirements

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

Quick Reference

Filtering, Sorting & Pagination

Bash 
# 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

Most list/index endpoints in this guide (TestCase, TestResult, Component, Process, Policy, Capability, Team) are intentionally unpaginated for backward compatibility and always return the full result set. Requirement, Persona, and UseCase are the exception: their index routes are paginated (default limit 25, keyset-based), so a large org’s full result set requires paging through page[limit]/page[offset] or page[after]/page[before] for keyset pagination — check the OpenAPI spec or Swagger UI for a given resource to confirm.

Create Example

Bash 
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

Status Meaning
200 Success (GET/PATCH)
201 Created (POST)
204 Deleted
401 Unauthorized
404 Not found
422 Validation failed

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