API Reference

The Cohera API provides programmatic access to all platform features. This reference documents every endpoint, request parameter, and response format.

Base URLs

Environment	Base URL
Production	`https://api.cohera.io/v1`
Sandbox	`https://sandbox.api.cohera.io/v1`

API Versioning

The API version is included in the URL path. The current version is v1.

When we make breaking changes, we’ll release a new version. Non-breaking changes (new fields, new endpoints) are added to the current version.

Version Lifecycle

Version	Status	Deprecation Date
v1	Current	-

Request Format

All API requests must include:

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Request Body Example

{
  "type": "supplier",
  "name": "Acme Chemicals",
  "attributes": {
    "country": "DE",
    "qualification_status": "qualified"
  }
}

Response Format

All responses follow a consistent structure:

Success Response

{
  "data": {
    "id": "ent_abc123",
    "type": "supplier",
    "name": "Acme Chemicals",
    "attributes": {...},
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

List Response

{
  "data": [
    {"id": "ent_abc123", ...},
    {"id": "ent_def456", ...}
  ],
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 25,
    "total_pages": 4
  },
  "links": {
    "self": "/v1/entities?page=1",
    "next": "/v1/entities?page=2",
    "last": "/v1/entities?page=4"
  }
}

Error Handling

Errors return appropriate HTTP status codes with detailed error information.

Error Response Structure

{
  "error": {
    "code": "validation_error",
    "message": "The request body contains invalid data",
    "details": [
      {
        "field": "attributes.country",
        "message": "Must be a valid ISO 3166-1 alpha-2 country code"
      }
    ],
    "request_id": "req_abc123def456"
  }
}

HTTP Status Codes

Code	Description
200	Success
201	Created
204	No Content (successful deletion)
400	Bad Request - Invalid input
401	Unauthorized - Invalid or missing credentials
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn’t exist
409	Conflict - Resource already exists or state conflict
422	Unprocessable Entity - Validation failed
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error
503	Service Unavailable

Error Codes

Code	Description
`validation_error`	Request body validation failed
`not_found`	Requested resource not found
`unauthorized`	Authentication failed
`forbidden`	Insufficient permissions
`conflict`	Resource state conflict
`rate_limit_exceeded`	Too many requests
`internal_error`	Server error

Pagination

List endpoints support cursor-based pagination for reliable results:

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	25	Items per page (max 100)
`cursor`	string	-	Cursor for cursor-based pagination

Example

curl "https://api.cohera.io/v1/entities?page=2&per_page=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filtering

Most list endpoints support filtering:

# Filter by type
curl "https://api.cohera.io/v1/entities?type=supplier" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by date range
curl "https://api.cohera.io/v1/entities?created_after=2024-01-01&created_before=2024-02-01" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Multiple filters
curl "https://api.cohera.io/v1/entities?type=supplier&attributes.country=DE" \
  -H "Authorization: Bearer YOUR_API_KEY"

Sorting

Use the sort parameter to order results:

# Sort by created date descending
curl "https://api.cohera.io/v1/entities?sort=-created_at" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Sort by name ascending
curl "https://api.cohera.io/v1/entities?sort=name" \
  -H "Authorization: Bearer YOUR_API_KEY"

Prefix with - for descending order.

Field Selection

Reduce response size by selecting specific fields:

curl "https://api.cohera.io/v1/entities?fields=id,name,type" \
  -H "Authorization: Bearer YOUR_API_KEY"

Idempotency

For POST requests, include an Idempotency-Key header to ensure the request is processed only once:

curl -X POST "https://api.cohera.io/v1/entities" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{"type": "supplier", "name": "Acme"}'

The idempotency key is valid for 24 hours.

Rate Limits

See the Authentication guide for rate limit details.

API Endpoints

Entities

Core entity management - create, read, update, delete. View documentation

Certificates

Certificate upload, validation, and expiry tracking. View documentation

Suppliers

Supplier management and qualification status. View documentation

Quality Events

Deviations, CAPAs, and audit findings. View documentation

Workflows

Workflow states, transitions, and approvals. View documentation

Audit Logs

Complete audit trail access and export. View documentation

SDKs and Client Libraries

Official SDKs are available at cohera.dev:

Python: pip install cohera
TypeScript/JavaScript: npm install @cohera/sdk
Go: go get github.com/cohera-io/cohera-go