Building Custom Integrations

Custom integrations connect Catalio with proprietary systems, legacy applications, and workflows that are not covered by a pre-built connector. The supported path today is Catalio’s REST API, used directly for request-response operations or polled on a schedule for synchronization.

Available Today

REST API

Catalio’s REST API uses JSON:API resource envelopes. Start with:

• JSON:API Overview for request shape, filtering, and pagination
• API Authentication for credentials and bearer tokens
• Swagger UI to inspect the available endpoints

Use the API for live reads and writes such as listing, creating, and updating requirements.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/vnd.api+json" \
  "https://catalio.ai/api/v1/requirements?page[limit]=50&page[offset]=0"

A JSON:API create request wraps attributes in a data envelope:

curl -X POST "https://catalio.ai/api/v1/requirements" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "Requirement",
      "attributes": {
        "title": "User authentication system",
        "user_want": "log in with multi-factor authentication",
        "user_benefit": "my account remains protected",
        "personas": [{"id": "<persona-uuid>"}]
      }
    }
  }'

At least one persona is required on create; look up persona IDs with GET /api/v1/personas first.

Scheduled Polling

Use polling when an external system needs to observe Catalio changes:

1. Call the relevant list endpoint on a schedule
2. Store the last complete response or the identifiers and timestamps you need
3. Diff each response against the previous poll
4. Apply changed records to the external system

The requirements list does not currently provide an incremental-sync filter, so each poll fetches the full list. Pace requests, follow pagination where the endpoint exposes it, and keep your own checkpoint only after a complete successful poll.

import os

import requests

api_key = os.environ["CATALIO_API_KEY"]
page_size = 50
offset = 0
current_requirements = []

while True:
    response = requests.get(
        "https://catalio.ai/api/v1/requirements",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Accept": "application/vnd.api+json",
        },
        params={"page[limit]": page_size, "page[offset]": offset},
        timeout=10,
    )
    response.raise_for_status()

    page = response.json()["data"]
    current_requirements.extend(page)

    if len(page) < page_size:
        break

    offset += len(page)

changed_requirements = diff_against_previous_poll(current_requirements)

For high-volume work, place API operations on your own queue and retry transient failures with backoff. Do not automatically retry non-idempotent creates.

Choose the Integration Shape

Authentication and Security

Follow the API Authentication guide for the currently supported authentication flows. Keep credentials in a secrets manager or environment variable, use HTTPS, and grant only the access the integration needs.

Handle API failures explicitly:

• Stop and refresh credentials on 401 Unauthorized
• Treat 403 Forbidden as an access problem, not a retryable outage
• Correct request data on 400 Bad Request or 422 Unprocessable Entity
• Back off on 429 Too Many Requests
• Retry idempotent operations on transient 5xx responses

Coming Soon: Outbound Webhooks

Until outbound webhooks ship, use scheduled polling. Any receiver or payload examples designed for future webhooks are architectural sketches, not a current Catalio API contract.

Catalio does receive inbound events from shipped integrations such as GitHub, Slack, Linear, and Microsoft Teams. That inbound behavior does not mean Catalio emits outbound webhook events for custom integrations.

Next Steps

1. Review the JSON:API Overview
2. Configure API Authentication
3. Test one idempotent read against the live REST API
4. Add writes with explicit duplicate and failure handling
5. Add scheduled polling if the external system needs Catalio changes

Need help? Contact support@catalio.ai.