Requirements API Reference

The Requirements API provides comprehensive access to Catalio’s core requirement management features. This API follows JSON:API v1.1 conventions and supports advanced capabilities including semantic search, AI-powered analysis, and multi-tenant data isolation.

New to the API? Start with the JSON:API Overview for a comprehensive introduction to Catalio’s API architecture.

Interactive Documentation

• Swagger UI: /api/swaggerui - Try the API interactively
• OpenAPI Spec: /api/v1/open_api - Download the complete API specification

Table of Contents

• API Overview
• Authentication
• JSON:API Format
• Core CRUD Operations
• Filtering and Querying
• Sorting and Pagination
• Relationships
• AI-Powered Features
• Bulk Operations
• Error Handling
• Common Patterns

API Overview

Base URL

/api/v1

Resource Endpoints

Authentication

All API requests require authentication using Bearer tokens. See the Authentication API guide for details.

GET /api/v1/requirements HTTP/1.1
Authorization: Bearer YOUR_TOKEN_HERE
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

Multi-Tenant Context

The API automatically enforces organization-level isolation based on the authenticated token. All queries are scoped to your organization, and you cannot access requirements from other organizations.

JSON:API Format

The Requirements API follows JSON:API v1.1 specification.

Standard Response Structure

{
  "data": {
    "id": "01JB2QE8V5X9R7M3P4N6K8W2Y1",
    "type": "requirement",
    "attributes": {
      "title": "Semantic search for requirements",
      "user_want": "search requirements using natural language queries",
      "user_benefit": "find related requirements even with different terminology",
      "status": "active",
      "priority": "high",
      "complexity": "complex",
      "business_value": "high",
      "ai_accessible": true,
      "inserted_at": "2025-03-01T10:30:00.000000Z",
      "updated_at": "2025-03-02T14:15:00.000000Z"
    },
    "relationships": {
      "personas": {
        "data": [{ "type": "persona", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y2" }]
      },
      "created_by": {
        "data": { "type": "user", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y3" }
      }
    }
  },
  "included": [
    {
      "id": "01JB2QE8V5X9R7M3P4N6K8W2Y2",
      "type": "persona",
      "attributes": {
        "name": "Business Analyst",
        "description": "Analyzes requirements and creates specifications"
      }
    }
  ],
  "meta": {
    "total_count": 142
  }
}

Collection Response Structure

{
  "data": [
    {
      "id": "01JB2QE8V5X9R7M3P4N6K8W2Y1",
      "type": "requirement",
      "attributes": {
        /* ... */
      }
    },
    {
      "id": "01JB2QE8V5X9R7M3P4N6K8W2Y4",
      "type": "requirement",
      "attributes": {
        /* ... */
      }
    }
  ],
  "meta": {
    "total_count": 142,
    "page": 1,
    "page_size": 25
  },
  "links": {
    "self": "/api/v1/requirements?page[number]=1",
    "next": "/api/v1/requirements?page[number]=2",
    "last": "/api/v1/requirements?page[number]=6"
  }
}

Core CRUD Operations

Create Requirement (POST)

Create a new requirement with personas and full specification.

Endpoint: POST /api/v1/requirements

Request Body:

{
  "data": {
    "type": "requirement",
    "attributes": {
      "title": "OAuth2 authentication integration",
      "user_want": "authenticate using OAuth2 with my Google account",
      "user_benefit": "I can access the system without managing another password",
      "status": "draft",
      "priority": "high",
      "complexity": "moderate",
      "business_value": "high",
      "source": "stakeholder",
      "discovery_method": "explicit",
      "confidence_level": "high",
      "confirmation_status": "pending",
      "ai_accessible": true,
      "assumptions": {
        "technical": ["Users have modern browsers", "Google OAuth2 API is stable"],
        "business": ["Users prefer social login over password management"]
      },
      "constraints": {
        "technical": ["Must support offline mode fallback"],
        "regulatory": ["GDPR compliance for data processing"]
      },
      "discovery_artifacts": {
        "documents": ["Meeting notes from 2025-02-15"],
        "references": ["Product roadmap Q2 2025"]
      }
    },
    "relationships": {
      "personas": {
        "data": [{ "type": "persona", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y2" }]
      },
      "reporter": {
        "data": { "type": "user", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y5" }
      }
    }
  }
}

Response: 201 Created

{
  "data": {
    "id": "01JB2QE8V5X9R7M3P4N6K8W2Y6",
    "type": "requirement",
    "attributes": {
      "title": "OAuth2 authentication integration",
      "user_want": "authenticate using OAuth2 with my Google account",
      "user_benefit": "I can access the system without managing another password",
      "status": "draft",
      "priority": "high",
      "complexity": "moderate",
      "business_value": "high",
      "ai_accessible": true,
      "inserted_at": "2025-03-02T15:30:00.000000Z",
      "updated_at": "2025-03-02T15:30:00.000000Z"
    },
    "relationships": {
      "personas": {
        "data": [{ "type": "persona", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y2" }]
      },
      "created_by": {
        "data": { "type": "user", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y3" }
      },
      "updated_by": {
        "data": { "type": "user", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y3" }
      }
    }
  }
}

Validation Rules:

• title - Required, unique per organization
• user_want - Required, describes the capability
• user_benefit - Required, describes the value/benefit
• personas - At least one persona required
• organization_id - Automatically set from auth token
• discovery_date - Required if discovery_method is implicit

Example with cURL:

curl -X POST /api/v1/requirements \
  -H "Authorization: Bearer ${CATALIO_TOKEN}" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "requirement",
      "attributes": {
        "title": "OAuth2 authentication integration",
        "user_want": "authenticate using OAuth2 with my Google account",
        "user_benefit": "I can access the system without managing another password",
        "priority": "high",
        "complexity": "moderate",
        "business_value": "high"
      },
      "relationships": {
        "personas": {
          "data": [
            { "type": "persona", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y2" }
          ]
        }
      }
    }
  }'

Read Requirement (GET)

Retrieve a single requirement by ID.

Endpoint: GET /api/v1/requirements/:id

Query Parameters:

Example Request:

GET /api/v1/requirements/01JB2QE8V5X9R7M3P4N6K8W2Y6?include=personas,created_by,use_cases HTTP/1.1
Authorization: Bearer YOUR_TOKEN_HERE
Accept: application/vnd.api+json

Response: 200 OK

{
  "data": {
    "id": "01JB2QE8V5X9R7M3P4N6K8W2Y6",
    "type": "requirement",
    "attributes": {
      "title": "OAuth2 authentication integration",
      "user_want": "authenticate using OAuth2 with my Google account",
      "user_benefit": "I can access the system without managing another password",
      "status": "active",
      "priority": "high",
      "complexity": "moderate",
      "business_value": "high",
      "source": "stakeholder",
      "discovery_method": "explicit",
      "confidence_level": "high",
      "confirmation_status": "confirmed",
      "ai_accessible": true,
      "ai_summary": "Enable Google OAuth2 authentication for passwordless access",
      "inserted_at": "2025-03-02T15:30:00.000000Z",
      "updated_at": "2025-03-05T10:15:00.000000Z"
    },
    "relationships": {
      "personas": {
        "data": [{ "type": "persona", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y2" }]
      },
      "created_by": {
        "data": { "type": "user", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y3" }
      },
      "use_cases": {
        "data": [{ "type": "use_case", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y7" }]
      }
    }
  },
  "included": [
    {
      "id": "01JB2QE8V5X9R7M3P4N6K8W2Y2",
      "type": "persona",
      "attributes": {
        "name": "Product Manager",
        "description": "Manages product features and roadmap"
      }
    },
    {
      "id": "01JB2QE8V5X9R7M3P4N6K8W2Y3",
      "type": "user",
      "attributes": {
        "full_name": "Jane Smith",
        "email": "jane.smith@example.com"
      }
    },
    {
      "id": "01JB2QE8V5X9R7M3P4N6K8W2Y7",
      "type": "use_case",
      "attributes": {
        "title": "Successful OAuth2 login flow",
        "scenario": "User clicks 'Sign in with Google' and grants permissions"
      }
    }
  ]
}

Example with cURL:

curl /api/v1/requirements/01JB2QE8V5X9R7M3P4N6K8W2Y6?include=personas,created_by \
  -H "Authorization: Bearer ${CATALIO_TOKEN}" \
  -H "Accept: application/vnd.api+json"

List Requirements (GET)

Retrieve all requirements with optional filtering and pagination.

Endpoint: GET /api/v1/requirements

Query Parameters:

Example Request:

GET /api/v1/requirements?page[number]=1&page[size]=25&include=personas&sort=-updated_at HTTP/1.1
Authorization: Bearer YOUR_TOKEN_HERE
Accept: application/vnd.api+json

Response: 200 OK

{
  "data": [
    {
      "id": "01JB2QE8V5X9R7M3P4N6K8W2Y6",
      "type": "requirement",
      "attributes": {
        "title": "OAuth2 authentication integration",
        "status": "active",
        "priority": "high",
        "updated_at": "2025-03-05T10:15:00.000000Z"
      },
      "relationships": {
        "personas": {
          "data": [{ "type": "persona", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y2" }]
        }
      }
    }
  ],
  "included": [
    {
      "id": "01JB2QE8V5X9R7M3P4N6K8W2Y2",
      "type": "persona",
      "attributes": {
        "name": "Product Manager"
      }
    }
  ],
  "meta": {
    "total_count": 142,
    "page": 1,
    "page_size": 25
  },
  "links": {
    "self": "/api/v1/requirements?page[number]=1&page[size]=25",
    "next": "/api/v1/requirements?page[number]=2&page[size]=25",
    "last": "/api/v1/requirements?page[number]=6&page[size]=25"
  }
}

Update Requirement (PATCH)

Update an existing requirement’s attributes or relationships.

Endpoint: PATCH /api/v1/requirements/:id

Request Body:

{
  "data": {
    "type": "requirement",
    "id": "01JB2QE8V5X9R7M3P4N6K8W2Y6",
    "attributes": {
      "status": "active",
      "priority": "critical",
      "confirmation_status": "confirmed",
      "assumptions": {
        "technical": ["Users have modern browsers", "OAuth2 API is stable"],
        "business": ["95% of users prefer social login"]
      }
    },
    "relationships": {
      "personas": {
        "data": [
          { "type": "persona", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y2" },
          { "type": "persona", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y8" }
        ]
      }
    }
  }
}

Response: 200 OK

{
  "data": {
    "id": "01JB2QE8V5X9R7M3P4N6K8W2Y6",
    "type": "requirement",
    "attributes": {
      "title": "OAuth2 authentication integration",
      "status": "active",
      "priority": "critical",
      "confirmation_status": "confirmed",
      "updated_at": "2025-03-05T14:30:00.000000Z"
    },
    "relationships": {
      "personas": {
        "data": [
          { "type": "persona", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y2" },
          { "type": "persona", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y8" }
        ]
      },
      "updated_by": {
        "data": { "type": "user", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y3" }
      }
    }
  }
}

Example with cURL:

curl -X PATCH /api/v1/requirements/01JB2QE8V5X9R7M3P4N6K8W2Y6 \
  -H "Authorization: Bearer ${CATALIO_TOKEN}" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "requirement",
      "id": "01JB2QE8V5X9R7M3P4N6K8W2Y6",
      "attributes": {
        "status": "active",
        "priority": "critical"
      }
    }
  }'

Delete Requirement (DELETE)

Archive a requirement (soft delete).

Endpoint: DELETE /api/v1/requirements/:id

Response: 204 No Content

Note: Requirements are soft-deleted (archived) rather than permanently deleted. The requirement is marked with an archived_at timestamp and excluded from normal queries. It can be restored through the admin interface if needed.

Example with cURL:

curl -X DELETE /api/v1/requirements/01JB2QE8V5X9R7M3P4N6K8W2Y6 \
  -H "Authorization: Bearer ${CATALIO_TOKEN}"

Filtering and Querying

Advanced Filtering (GET)

Use the filtered endpoint for complex multi-criteria queries.

Endpoint: GET /api/v1/requirements/filtered

Query Parameters:

Example Request:

GET /api/v1/requirements/filtered?status=active&priority=high&search=authentication HTTP/1.1
Authorization: Bearer YOUR_TOKEN_HERE
Accept: application/vnd.api+json

Response: 200 OK

{
  "data": [
    {
      "id": "01JB2QE8V5X9R7M3P4N6K8W2Y6",
      "type": "requirement",
      "attributes": {
        "title": "OAuth2 authentication integration",
        "status": "active",
        "priority": "high",
        "user_want": "authenticate using OAuth2"
      }
    }
  ],
  "meta": {
    "total_count": 3,
    "filters_applied": {
      "status": "active",
      "priority": "high",
      "search": "authentication"
    }
  }
}

Filter Combinations:

# Active, high priority requirements
GET /api/v1/requirements/filtered?status=active&priority=high

# Search across all text fields
GET /api/v1/requirements/filtered?search=export%20csv

# Combine filters with pagination
GET /api/v1/requirements/filtered?status=draft&page[size]=50

# Search with relationship includes
GET /api/v1/requirements/filtered?search=oauth&include=personas,created_by

Available Filter Values

Status:

• draft - Work in progress
• active - Approved and in development
• deprecated - Phased out
• superseded - Replaced by newer requirement
• archived - No longer relevant

Priority:

• low - Future consideration
• medium - Standard priority
• high - Important for next release
• critical - Blocking or urgent

Confirmation Status:

• pending - Awaiting review
• confirmed - Stakeholder approved
• rejected - Stakeholder declined
• investigation - Needs further research

Sorting and Pagination

Sort Options

Sort requirements using the sort query parameter. Prefix field names with - for descending order.

Available Sort Fields:

Examples:

# Sort by title ascending
GET /api/v1/requirements?sort=title

# Sort by priority descending, then title ascending
GET /api/v1/requirements?sort=-priority,title

# Sort by most recently updated
GET /api/v1/requirements?sort=-updated_at

Pagination

The API uses offset-based pagination with page[number] and page[size].

Pagination Parameters:

Example Pagination:

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

# Third page with 50 results
GET /api/v1/requirements?page[number]=3&page[size]=50

# Maximum page size
GET /api/v1/requirements?page[size]=100

Pagination Response:

{
  "data": [
    /* requirements */
  ],
  "meta": {
    "total_count": 142,
    "page": 2,
    "page_size": 25
  },
  "links": {
    "self": "/api/v1/requirements?page[number]=2&page[size]=25",
    "first": "/api/v1/requirements?page[number]=1&page[size]=25",
    "prev": "/api/v1/requirements?page[number]=1&page[size]=25",
    "next": "/api/v1/requirements?page[number]=3&page[size]=25",
    "last": "/api/v1/requirements?page[number]=6&page[size]=25"
  }
}

Relationships

Including Relationships

Use the include parameter to load related resources in a single request (eager loading).

Available Relationships:

Example with Multiple Relationships:

GET /api/v1/requirements/01JB2QE8V5X9R7M3P4N6K8W2Y6?include=personas,created_by,use_cases,use_cases.test_cases HTTP/1.1

Response with Nested Relationships:

{
  "data": {
    "id": "01JB2QE8V5X9R7M3P4N6K8W2Y6",
    "type": "requirement",
    "attributes": {
      /* requirement attributes */
    },
    "relationships": {
      "personas": {
        "data": [{ "type": "persona", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y2" }]
      },
      "use_cases": {
        "data": [{ "type": "use_case", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y7" }]
      }
    }
  },
  "included": [
    {
      "id": "01JB2QE8V5X9R7M3P4N6K8W2Y2",
      "type": "persona",
      "attributes": {
        "name": "Product Manager"
      }
    },
    {
      "id": "01JB2QE8V5X9R7M3P4N6K8W2Y7",
      "type": "use_case",
      "attributes": {
        "title": "Successful OAuth2 login flow"
      },
      "relationships": {
        "test_cases": {
          "data": [{ "type": "test_case", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y9" }]
        }
      }
    },
    {
      "id": "01JB2QE8V5X9R7M3P4N6K8W2Y9",
      "type": "test_case",
      "attributes": {
        "title": "User clicks Google sign-in button",
        "expected_result": "User is redirected to Google OAuth2 consent screen"
      }
    }
  ]
}

Detail View (GET)

Get a requirement with all relationships pre-loaded for display.

Endpoint: GET /api/v1/requirements/:id/detail

This endpoint automatically includes:

• Personas
• Created by, updated by, reporter (with full names)
• Use cases with nested test cases and test results
• Superseding relationships (both directions)
• AI analysis results
• Process relationships
• Component relationships with implementation status

Example Request:

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

AI-Powered Features

Semantic Search (POST)

Search requirements using natural language queries based on semantic similarity.

Endpoint: POST /api/v1/requirements/semantic-search

Request Body:

{
  "query": "user authentication and login",
  "limit": 10
}

Response: 200 OK

{
  "data": [
    {
      "id": "01JB2QE8V5X9R7M3P4N6K8W2Y6",
      "type": "requirement",
      "attributes": {
        "title": "OAuth2 authentication integration",
        "user_want": "authenticate using OAuth2 with my Google account",
        "similarity_score": 0.92
      }
    },
    {
      "id": "01JB2QE8V5X9R7M3P4N6K8W2YA",
      "type": "requirement",
      "attributes": {
        "title": "Multi-factor authentication",
        "user_want": "enable two-factor authentication for enhanced security",
        "similarity_score": 0.87
      }
    }
  ],
  "meta": {
    "query": "user authentication and login",
    "total_results": 5,
    "threshold": 0.8
  }
}

How It Works:

1. The query is converted to a vector embedding using OpenAI’s embedding model
2. Cosine distance is calculated between the query vector and requirement vectors
3. Results with distance < 0.8 are returned (closer = more similar)
4. Results are sorted by relevance (most similar first)

Use Cases:

• Find related requirements using different terminology
• Discover duplicate or overlapping requirements
• Identify requirements affected by proposed changes
• Build requirement recommendation systems

Example with cURL:

curl -X POST /api/v1/requirements/semantic-search \
  -H "Authorization: Bearer ${CATALIO_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "export data to spreadsheet",
    "limit": 5
  }'

Sentiment Analysis (POST)

Analyze stakeholder sentiment expressed in requirement text.

Endpoint: POST /api/v1/requirements/:id/analyze-sentiment

Request Body:

{
  "text": "need urgent fix for broken export functionality"
}

If text is omitted, the requirement’s user_want field is analyzed.

Response: 200 OK

{
  "sentiment": "concerned",
  "confidence": 0.89,
  "reasoning": "Language indicates urgency and problem-focused concern"
}

Sentiment Values:

• positive - Enthusiastic, optimistic tone
• neutral - Factual, objective description
• concerned - Risk-aware, highlighting issues
• negative - Resistant or critical tone

Update Requirement with Sentiment:

The sentiment can be stored on the requirement:

# Analyze sentiment
SENTIMENT=$(curl -X POST /api/v1/requirements/01JB2QE8V5X9R7M3P4N6K8W2Y6/analyze-sentiment \
  -H "Authorization: Bearer ${CATALIO_TOKEN}" | jq -r '.sentiment')

# Update requirement
curl -X PATCH /api/v1/requirements/01JB2QE8V5X9R7M3P4N6K8W2Y6 \
  -H "Authorization: Bearer ${CATALIO_TOKEN}" \
  -H "Content-Type: application/vnd.api+json" \
  -d "{\"data\":{\"type\":\"requirement\",\"id\":\"01JB2QE8V5X9R7M3P4N6K8W2Y6\",\"attributes\":{\"ai_sentiment_result\":\"${SENTIMENT}\"}}}"

Quality Assessment (POST)

Get AI-powered quality assessment with specific improvement suggestions.

Endpoint: POST /api/v1/requirements/:id/assess-quality

Request Body (optional):

{
  "title": "Better reports",
  "description": "Users want reporting"
}

If fields are omitted, the requirement’s actual values are used.

Response: 200 OK

{
  "quality_score": 4,
  "completeness_score": 3,
  "clarity_score": 5,
  "improvement_suggestions": [
    "Specify which personas need reporting (e.g., Business Analyst, Manager)",
    "Define what types of reports are needed (financial, operational, compliance)",
    "Clarify the business benefit beyond 'better' - what outcome is expected?"
  ],
  "missing_elements": [
    "Specific report formats (PDF, CSV, Excel)",
    "Expected data sources",
    "Performance requirements (report generation time)",
    "Acceptance criteria or use cases"
  ],
  "overall_assessment": "Requirement is too vague. Needs specific personas, report types, and measurable benefits."
}

Scores: 1-10 scale (10 = excellent)

Category Suggestions (POST)

Get AI suggestions for priority, complexity, and business value categorization.

Endpoint: POST /api/v1/requirements/:id/suggest-categories

Response: 200 OK

{
  "suggested_priority": "high",
  "priority_reasoning": "Reporting is a core business capability and stakeholder requested feature",
  "suggested_complexity": "moderate",
  "complexity_reasoning": "Requires data aggregation, multiple export formats, and permission handling",
  "suggested_business_value": "high",
  "business_value_reasoning": "Enables data-driven decision making and stakeholder reporting",
  "suggested_tags": ["reporting", "data-export", "analytics", "csv-export"],
  "confidence": "medium"
}

Applying Suggestions:

# Get suggestions
curl -X POST /api/v1/requirements/01JB2QE8V5X9R7M3P4N6K8W2Y6/suggest-categories \
  -H "Authorization: Bearer ${CATALIO_TOKEN}" > suggestions.json

# Apply to requirement
PRIORITY=$(jq -r '.suggested_priority' suggestions.json)
COMPLEXITY=$(jq -r '.suggested_complexity' suggestions.json)
VALUE=$(jq -r '.suggested_business_value' suggestions.json)

curl -X PATCH /api/v1/requirements/01JB2QE8V5X9R7M3P4N6K8W2Y6 \
  -H "Authorization: Bearer ${CATALIO_TOKEN}" \
  -H "Content-Type: application/vnd.api+json" \
  -d "{\"data\":{\"type\":\"requirement\",\"attributes\":{\"priority\":\"${PRIORITY}\",\"complexity\":\"${COMPLEXITY}\",\"business_value\":\"${VALUE}\"}}}"

Generate AI Summary (POST)

Generate a concise 200-character summary for AI context and previews.

Endpoint: POST /api/v1/requirements/:id/generate-summary

Response: 200 OK

{
  "summary": "Enable Google OAuth2 authentication for passwordless access to the system, improving user experience and security."
}

Update Requirement:

# Generate summary
SUMMARY=$(curl -X POST /api/v1/requirements/01JB2QE8V5X9R7M3P4N6K8W2Y6/generate-summary \
  -H "Authorization: Bearer ${CATALIO_TOKEN}" | jq -r '.summary')

# Save to requirement
curl -X PATCH /api/v1/requirements/01JB2QE8V5X9R7M3P4N6K8W2Y6 \
  -H "Authorization: Bearer ${CATALIO_TOKEN}" \
  -H "Content-Type: application/vnd.api+json" \
  -d "{\"data\":{\"type\":\"requirement\",\"attributes\":{\"ai_summary\":\"${SUMMARY}\"}}}"

Generate Semantic Tags (POST)

Generate categorized tags for search and organization.

Endpoint: POST /api/v1/requirements/:id/generate-tags

Response: 200 OK

{
  "functional_area": ["authentication", "security"],
  "technical_concepts": ["oauth2", "api", "identity-provider"],
  "domain_terms": ["single-sign-on", "user-access"],
  "user_actions": ["login", "authenticate", "authorize"],
  "features": ["social-login", "google-integration"]
}

AI Privacy Control

All AI features respect the ai_accessible attribute. Requirements with ai_accessible: false are excluded from:

• Semantic search results
• AI analysis operations
• Vector embedding generation

Disable AI for Sensitive Requirements:

curl -X PATCH /api/v1/requirements/01JB2QE8V5X9R7M3P4N6K8W2Y6 \
  -H "Authorization: Bearer ${CATALIO_TOKEN}" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "requirement",
      "attributes": {
        "ai_accessible": false
      }
    }
  }'

Bulk Operations

Bulk Create

Create multiple requirements in a single request.

Endpoint: POST /api/v1/requirements/bulk

Request Body:

{
  "data": [
    {
      "type": "requirement",
      "attributes": {
        "title": "OAuth2 authentication",
        "user_want": "authenticate using OAuth2",
        "user_benefit": "passwordless access"
      },
      "relationships": {
        "personas": {
          "data": [{ "type": "persona", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y2" }]
        }
      }
    },
    {
      "type": "requirement",
      "attributes": {
        "title": "CSV export functionality",
        "user_want": "export data as CSV",
        "user_benefit": "analyze in Excel"
      },
      "relationships": {
        "personas": {
          "data": [{ "type": "persona", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y2" }]
        }
      }
    }
  ]
}

Response: 201 Created

{
  "data": [
    {
      "id": "01JB2QE8V5X9R7M3P4N6K8W2Y6",
      "type": "requirement",
      "attributes": {
        "title": "OAuth2 authentication"
      }
    },
    {
      "id": "01JB2QE8V5X9R7M3P4N6K8W2YB",
      "type": "requirement",
      "attributes": {
        "title": "CSV export functionality"
      }
    }
  ],
  "meta": {
    "created_count": 2
  }
}

Bulk Update

Update multiple requirements with a single request.

Endpoint: PATCH /api/v1/requirements/bulk

Request Body:

{
  "data": [
    {
      "id": "01JB2QE8V5X9R7M3P4N6K8W2Y6",
      "type": "requirement",
      "attributes": {
        "status": "active"
      }
    },
    {
      "id": "01JB2QE8V5X9R7M3P4N6K8W2YB",
      "type": "requirement",
      "attributes": {
        "priority": "high"
      }
    }
  ]
}

Bulk State Transitions

Activate multiple requirements at once.

Endpoint: POST /api/v1/requirements/bulk-activate

Request Body:

{
  "requirement_ids": [
    "01JB2QE8V5X9R7M3P4N6K8W2Y6",
    "01JB2QE8V5X9R7M3P4N6K8W2YB",
    "01JB2QE8V5X9R7M3P4N6K8W2YC"
  ]
}

Response: 200 OK

{
  "data": [
    {
      "id": "01JB2QE8V5X9R7M3P4N6K8W2Y6",
      "type": "requirement",
      "attributes": {
        "status": "active"
      }
    }
  ],
  "meta": {
    "updated_count": 3
  }
}

Error Handling

Error Response Format

All errors follow JSON:API error specification:

{
  "errors": [
    {
      "status": "422",
      "code": "validation_error",
      "title": "Validation Error",
      "detail": "Requirement title is required",
      "source": {
        "pointer": "/data/attributes/title"
      }
    }
  ]
}

Common Error Codes

Validation Errors

Multiple validation errors are returned together:

{
  "errors": [
    {
      "status": "422",
      "code": "validation_error",
      "detail": "Requirement title is required",
      "source": { "pointer": "/data/attributes/title" }
    },
    {
      "status": "422",
      "code": "validation_error",
      "detail": "User want (capability) is required",
      "source": { "pointer": "/data/attributes/user_want" }
    },
    {
      "status": "422",
      "code": "validation_error",
      "detail": "At least one persona is required",
      "source": { "pointer": "/data/relationships/personas" }
    }
  ]
}

AI Feature Errors

AI operations may fail with specific error messages:

{
  "errors": [
    {
      "status": "403",
      "code": "ai_access_denied",
      "title": "AI Access Denied",
      "detail": "This requirement has AI access disabled (ai_accessible: false)"
    }
  ]
}

{
  "errors": [
    {
      "status": "500",
      "code": "llm_request_failed",
      "title": "LLM Request Failed",
      "detail": "OpenAI API timeout after 20 seconds"
    }
  ]
}

Multi-Tenant Errors

Attempting to access requirements from another organization:

{
  "errors": [
    {
      "status": "404",
      "code": "not_found",
      "title": "Resource Not Found",
      "detail": "Requirement not found or you don't have access to it"
    }
  ]
}

Note: For security, the API returns 404 (not found) rather than 403 (forbidden) when accessing cross-tenant resources. This prevents information disclosure about other organizations’ data.

Common Patterns

Complete Requirement Lifecycle

# 1. Create draft requirement
REQ_ID=$(curl -X POST /api/v1/requirements \
  -H "Authorization: Bearer ${CATALIO_TOKEN}" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "requirement",
      "attributes": {
        "title": "OAuth2 authentication",
        "user_want": "authenticate using OAuth2",
        "user_benefit": "passwordless access",
        "status": "draft"
      },
      "relationships": {
        "personas": {
          "data": [{"type": "persona", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y2"}]
        }
      }
    }
  }' | jq -r '.data.id')

# 2. Get AI quality assessment
curl -X POST "/api/v1/requirements/${REQ_ID}/assess-quality" \
  -H "Authorization: Bearer ${CATALIO_TOKEN}"

# 3. Get categorization suggestions
curl -X POST "/api/v1/requirements/${REQ_ID}/suggest-categories" \
  -H "Authorization: Bearer ${CATALIO_TOKEN}"

# 4. Generate summary
SUMMARY=$(curl -X POST "/api/v1/requirements/${REQ_ID}/generate-summary" \
  -H "Authorization: Bearer ${CATALIO_TOKEN}" | jq -r '.summary')

# 5. Update with AI-generated content
curl -X PATCH "/api/v1/requirements/${REQ_ID}" \
  -H "Authorization: Bearer ${CATALIO_TOKEN}" \
  -H "Content-Type: application/vnd.api+json" \
  -d "{\"data\":{\"type\":\"requirement\",\"attributes\":{\"ai_summary\":\"${SUMMARY}\",\"priority\":\"high\",\"complexity\":\"moderate\"}}}"

# 6. Confirm requirement
curl -X POST "/api/v1/requirements/${REQ_ID}/confirm" \
  -H "Authorization: Bearer ${CATALIO_TOKEN}"

# 7. Activate requirement
curl -X POST "/api/v1/requirements/${REQ_ID}/activate" \
  -H "Authorization: Bearer ${CATALIO_TOKEN}"

Search and Filter Pipeline

# 1. Text search for candidates
curl "/api/v1/requirements/filtered?search=authentication" \
  -H "Authorization: Bearer ${CATALIO_TOKEN}"

# 2. Semantic search for similar requirements
curl -X POST /api/v1/requirements/semantic-search \
  -H "Authorization: Bearer ${CATALIO_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"query": "user login and access control", "limit": 10}'

# 3. Filter by status and priority
curl "/api/v1/requirements/filtered?status=active&priority=high" \
  -H "Authorization: Bearer ${CATALIO_TOKEN}"

Requirement Evolution (Superseding)

# 1. Create new improved requirement
NEW_REQ_ID=$(curl -X POST /api/v1/requirements \
  -H "Authorization: Bearer ${CATALIO_TOKEN}" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "requirement",
      "attributes": {
        "title": "OAuth2 and SAML authentication",
        "user_want": "authenticate using OAuth2 or SAML",
        "user_benefit": "flexible SSO options"
      },
      "relationships": {
        "personas": {
          "data": [{"type": "persona", "id": "01JB2QE8V5X9R7M3P4N6K8W2Y2"}]
        }
      }
    }
  }' | jq -r '.data.id')

# 2. Supersede old requirement with new one
curl -X POST "/api/v1/requirements/${OLD_REQ_ID}/supersede" \
  -H "Authorization: Bearer ${CATALIO_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"superseding_requirement_id\": \"${NEW_REQ_ID}\",
    \"reason\": \"Expanded to support both OAuth2 and SAML\",
    \"notes\": \"Customer feedback showed need for enterprise SAML support\"
  }"

# 3. Activate new requirement
curl -X POST "/api/v1/requirements/${NEW_REQ_ID}/activate" \
  -H "Authorization: Bearer ${CATALIO_TOKEN}"

Export Requirements

# Get all active requirements with full relationships
curl "/api/v1/requirements/filtered?status=active&include=personas,use_cases,created_by" \
  -H "Authorization: Bearer ${CATALIO_TOKEN}" \
  -H "Accept: application/vnd.api+json" > requirements.json

# Convert to CSV (using jq)
jq -r '.data[] | [.id, .attributes.title, .attributes.status, .attributes.priority] | @csv' \
  requirements.json > requirements.csv

Organization Statistics

# Get comprehensive stats
curl /api/v1/requirements/stats \
  -H "Authorization: Bearer ${CATALIO_TOKEN}"

Response:

{
  "total": 142,
  "active_count": 87,
  "draft_count": 32,
  "deprecated_count": 15,
  "high_priority_count": 45,
  "medium_priority_count": 68,
  "low_priority_count": 29,
  "validated_count": 98,
  "ai_summary_count": 112,
  "use_case_coverage": {
    "coverage_percentage": 78.5,
    "total_requirements": 142,
    "requirements_with_use_cases": 111
  },
  "ai_summary_coverage": {
    "coverage_percentage": 78.9
  },
  "test_coverage": {
    "coverage_percentage": 65.2,
    "total_requirements": 142,
    "requirements_with_tests": 92
  },
  "quality_score": {
    "score": 72.3,
    "components": {
      "validation": 69.0,
      "use_case_coverage": 78.5,
      "test_coverage": 65.2,
      "ai_enhancement": 78.9
    }
  }
}

Integration Example: Sync from Jira

#!/bin/bash
# Sync requirements from Jira to Catalio

# Get Jira issues
JIRA_ISSUES=$(curl "https://your-domain.atlassian.net/rest/api/3/search?jql=project=PROJ" \
  -H "Authorization: Basic ${JIRA_TOKEN}")

# Convert to Catalio requirements
echo $JIRA_ISSUES | jq -c '.issues[]' | while read issue; do
  TITLE=$(echo $issue | jq -r '.fields.summary')

  curl -X POST /api/v1/requirements \
    -H "Authorization: Bearer ${CATALIO_TOKEN}" \
    -H "Content-Type: application/vnd.api+json" \
    -d "{
      \"data\": {
        \"type\": \"requirement\",
        \"attributes\": {
          \"title\": \"${TITLE}\",
          \"user_want\": \"${DESCRIPTION}\",
          \"user_benefit\": \"imported from Jira\",
          \"source\": \"other\",
          \"discovery_artifacts\": {
            \"jira\": [\"$(echo $issue | jq -r '.key')\"]
          }
        },
        \"relationships\": {
          \"personas\": {
            \"data\": [{\"type\": \"persona\", \"id\": \"${DEFAULT_PERSONA_ID}\"}]
          }
        }
      }
    }"
done

Best Practices

API Design Principles

1. Always include relationships - Use ?include=personas,created_by to avoid N+1 queries
2. Use filtered endpoint - For complex queries, use /requirements/filtered instead of manual filtering
3. Leverage semantic search - Find related requirements even with different terminology
4. Respect AI privacy - Check ai_accessible before AI operations
5. Handle multi-tenant correctly - Never hardcode organization IDs
6. Use bulk operations - For multiple changes, use bulk endpoints to reduce API calls
7. Implement pagination - Always paginate large result sets
8. Cache when appropriate - Cache persona lists, stats, etc. that don’t change frequently

Performance Tips

1. Sparse fieldsets - Request only needed fields: ?fields[requirement]=title,status,priority
2. Limit relationships - Only include relationships you need
3. Use detail endpoint - For show pages, use /requirements/:id/detail to get everything in one request
4. Batch AI operations - Run AI analysis asynchronously for multiple requirements
5. Monitor rate limits - Check X-RateLimit-* headers and implement backoff

Error Handling

async function createRequirement(data) {
  try {
    const response = await fetch('/api/v1/requirements', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/vnd.api+json',
      },
      body: JSON.stringify(data),
    })

    if (!response.ok) {
      const errorData = await response.json()

      if (response.status === 422) {
        // Handle validation errors
        const errors = errorData.errors.map((e) => ({
          field: e.source.pointer,
          message: e.detail,
        }))
        throw new ValidationError(errors)
      }

      if (response.status === 429) {
        // Handle rate limiting
        const retryAfter = response.headers.get('Retry-After')
        throw new RateLimitError(`Retry after ${retryAfter} seconds`)
      }

      throw new APIError(errorData.errors[0].detail)
    }

    return await response.json()
  } catch (error) {
    console.error('Failed to create requirement:', error)
    throw error
  }
}

Next Steps

Related Resource APIs

• JSON:API Overview - Complete API introduction and quick start guide
• Personas API - Manage user personas and stakeholders
• Use Cases API - Work with acceptance criteria and scenarios
• Test Cases API - Test specifications and execution
• Components API - System components and architecture
• Processes API - Business processes and workflows

Additional Topics

• Authentication API - Token management and authentication
• Webhooks - Real-time event notifications
• GraphQL API - Flexible querying (coming soon)
• Best Practices - Patterns, performance, error handling

Interactive Resources

• Swagger UI: /api/swaggerui - Test the API interactively
• OpenAPI Spec: /api/v1/open_api - Download the complete specification
• API Status: /status - Check API health and uptime

Support

Questions about the Requirements API?

• In-App Help: Type /help in the AI chat for interactive assistance
• Email: support@catalio.com
• Interactive Documentation: /api/swaggerui - Test endpoints and explore examples