JSON:API Overview

Catalio provides a JSON:API implementation following the JSON:API v1.1 specification. For complete endpoint details, schemas, and live testing, use our interactive documentation.

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:

Navigate to /api/swaggerui
Click Authorize and enter: Bearer YOUR_TOKEN_HERE
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

# Paginate
GET /api/v1/requirements?page[number]=1&page[size]=25

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

# Combine all
GET /api/v1/requirements?filter[status]=active&sort=-priority&page[size]=50&include=personas

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"
      }
    }
  }'

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

Swagger UI - Explore and test endpoints interactively