API Reference¶

DIBOP provides a RESTful API that allows you to interact with the platform programmatically. This page provides an overview of the API, authentication, and key endpoints.

API Documentation (Swagger)¶

The full, interactive API documentation is available at:

https://<your-instance>.dibop.ca/api/v1/docs

This Swagger/OpenAPI interface lets you:

Browse all available endpoints
See request and response schemas
Try out API calls directly from the browser (when authenticated)

Base URL¶

All API endpoints are prefixed with:

https://<your-instance>.dibop.ca/api/v1/

For example, the orchestrations endpoint is:

https://<your-instance>.dibop.ca/api/v1/orchestrations

Authentication¶

The DIBOP API uses JWT Bearer tokens for authentication.

Obtaining a Token¶

From the UI¶

If you have an API key configured in Enterprise Settings, use it as a Bearer token:

curl -H "Authorization: Bearer <your-api-key>" \
  https://<your-instance>.dibop.ca/api/v1/orchestrations

From the Auth Endpoint¶

Authenticate with email and password to receive a JWT:

curl -X POST https://<your-instance>.dibop.ca/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600
}

Using the Token¶

Include the token in the Authorization header of every request:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://<your-instance>.dibop.ca/api/v1/orchestrations

Token Expiry¶

Tokens expire after the configured session duration (typically 1-4 hours). When a token expires, you receive a 401 response. Request a new token by authenticating again.

Key Endpoints¶

Orchestrations¶

Method	Endpoint	Description
`GET`	`/orchestrations`	List all orchestrations
`GET`	`/orchestrations/{id}`	Get a specific orchestration
`POST`	`/orchestrations`	Create a new orchestration
`PUT`	`/orchestrations/{id}`	Update an orchestration
`DELETE`	`/orchestrations/{id}`	Delete an orchestration
`POST`	`/orchestrations/{id}/execute`	Execute an orchestration

Execute an Orchestration¶

curl -X POST https://<your-instance>.dibop.ca/api/v1/orchestrations/{id}/execute \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "vin": "1HGCM82633A004352"
    }
  }'

Response:

{
  "execution_id": "exec-abc123",
  "status": "running",
  "started_at": "2026-04-08T10:30:00Z"
}

Executions¶

Method	Endpoint	Description
`GET`	`/orchestrations/{id}/executions`	List executions for an orchestration
`GET`	`/executions/{execution_id}`	Get execution detail with step results
`GET`	`/executions/{execution_id}/trace`	Get the full execution trace

Connections¶

Method	Endpoint	Description
`GET`	`/systems`	List all available systems in the catalogue
`GET`	`/systems/{slug}/apis`	List registered APIs for a system
`POST`	`/systems/{slug}/ping`	Ping a system to check health

API Call Logs¶

Method	Endpoint	Description
`GET`	`/api-calls`	List API call logs (paginated)
`GET`	`/api-calls/systems`	Get per-system statistics

Query Parameters for API Calls¶

Parameter	Type	Description
`system`	String	Filter by system slug
`status`	String	Filter by status: `success`, `error`, `timeout`
`from`	DateTime	Start of date range (ISO 8601)
`to`	DateTime	End of date range (ISO 8601)
`page`	Integer	Page number (default: 1)
`page_size`	Integer	Results per page (default: 50, max: 200)

Canonical Data¶

Method	Endpoint	Description
`GET`	`/canonical`	List all CDM domains
`GET`	`/canonical/{domain}`	List records for a domain
`GET`	`/canonical/{domain}/{id}`	Get a specific record
`POST`	`/canonical/{domain}`	Create a canonical record

Observability¶

Method	Endpoint	Description
`GET`	`/observability/sla`	Get SLA metrics
`GET`	`/observability/metrics`	Get platform metrics

Alert Rules¶

Method	Endpoint	Description
`GET`	`/alert-rules`	List all alert rules
`POST`	`/alert-rules`	Create a new alert rule
`PUT`	`/alert-rules/{id}`	Update an alert rule
`DELETE`	`/alert-rules/{id}`	Delete an alert rule

Request and Response Format¶

Content Type¶

All requests and responses use JSON:

Content-Type: application/json

Pagination¶

List endpoints return paginated results:

{
  "items": [...],
  "total": 150,
  "page": 1,
  "page_size": 50,
  "pages": 3
}

Use the page and page_size query parameters to navigate:

GET /api/v1/api-calls?page=2&page_size=50

Error Responses¶

Error responses follow a consistent format:

{
  "detail": "Orchestration not found",
  "status_code": 404,
  "error_code": "NOT_FOUND"
}

Common error codes:

Status	Error Code	Meaning
400	`BAD_REQUEST`	Invalid request parameters
401	`UNAUTHORIZED`	Missing or invalid authentication token
403	`FORBIDDEN`	Authenticated but insufficient permissions
404	`NOT_FOUND`	Resource does not exist
409	`CONFLICT`	Resource already exists or state conflict
422	`VALIDATION_ERROR`	Request body failed validation
429	`RATE_LIMIT`	Too many requests
500	`INTERNAL_ERROR`	Server error

Rate Limiting¶

The DIBOP API applies rate limits per enterprise:

Scope	Limit
API calls to DIBOP	300 requests/minute
Orchestration executions	60 executions/minute

When rate limited, the response includes:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1712582400
Retry-After: 15

Wait for the Retry-After seconds before retrying.

Webhooks (Incoming)¶

DIBOP can receive webhooks from external systems to trigger orchestrations:

curl -X POST https://<your-instance>.dibop.ca/api/v1/webhooks/{webhook_id} \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: <secret>" \
  -d '{
    "event": "vehicle_updated",
    "vin": "WDB1234567890",
    "timestamp": "2026-04-08T10:30:00Z"
  }'

Configure incoming webhooks in Enterprise Settings.

SDKs and Client Libraries¶

DIBOP does not currently provide official SDKs, but the API is standard REST with JSON payloads and can be consumed from any language using standard HTTP libraries:

Language	Recommended Library
Python	`httpx` or `requests`
JavaScript/TypeScript	`fetch` or `axios`
C#	`HttpClient`
Go	`net/http`
Java	`HttpClient` (Java 11+)

Best Practices¶

Use API keys for automation -- generate dedicated API keys for CI/CD pipelines and scheduled tasks
Handle rate limits gracefully -- implement exponential backoff when receiving 429 responses
Paginate large results -- always use pagination for list endpoints; do not try to fetch all records at once
Cache static data -- system catalogues and CDM schemas change infrequently; cache them locally
Monitor token expiry -- refresh tokens before they expire to avoid interrupted workflows

Next Steps¶

Glossary -- definitions of all DIBOP terms
Orchestrations -- understand what you can automate via the API
Enterprise Settings -- generate API keys