API Overview

The Inherent API is organized around REST. It accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

Base URL

https://api.inherent.systems/api/v1

Authentication

All API requests require authentication using a Bearer token:

curl https://api.inherent.systems/api/v1/documents \
  -H "Authorization: Bearer inh_live_abc123..."

See the Authentication Guide for details on creating and managing API keys.

Request Format

Send JSON in request bodies:

curl -X POST https://api.inherent.systems/api/v1/search \
  -H "Authorization: Bearer $INHERENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "your search query"}'

Response Format

All responses are JSON:

{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "latency_ms": 45
  }
}

Errors

Errors follow a consistent format:

{
  "error": {
    "code": "invalid_request",
    "message": "The 'query' field is required",
    "param": "query",
    "request_id": "req_abc123"
  }
}

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad request - invalid parameters
401	Unauthorized - invalid or missing API key
403	Forbidden - insufficient permissions
404	Not found
429	Rate limit exceeded
500	Server error

Error Codes

Code	Description
invalid_request	Request body is malformed
missing_parameter	Required parameter is missing
invalid_parameter	Parameter value is invalid
resource_not_found	Requested resource doesn't exist
rate_limit_exceeded	Too many requests
quota_exceeded	Plan quota reached
internal_error	Server-side error

Pagination

List endpoints support pagination:

curl "https://api.inherent.systems/api/v1/documents?limit=20&cursor=doc_abc123" \
  -H "Authorization: Bearer $INHERENT_API_KEY"

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "has_more": true,
    "next_cursor": "doc_xyz789",
    "total": 150
  }
}

Rate Limits

Plan	Requests/minute	Requests/day
Free	60	10,000
Pro	300	100,000
Enterprise	Custom	Custom

Rate limit headers are included in responses:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1705312800

Versioning

The API is versioned via the URL path (/api/v1/). Breaking changes will be released in new versions.

API Endpoints

Search

Method	Endpoint	Description
POST	/search	Semantic search

Documents

Method	Endpoint	Description
GET	/documents	List documents
GET	/documents/:id	Get document

Chunks

Method	Endpoint	Description
GET	/chunks/:document_id	Get document chunks
GET	/chunks/:document_id/context	Get full document context

Ingestion (Coming Soon)

Method	Endpoint	Description
POST	/documents	Upload a document
POST	/documents/url	Import from URL
GET	/documents/:id/status	Get processing status

Workspaces (Coming Soon)

Method	Endpoint	Description
POST	/workspaces	Create workspace
GET	/workspaces	List workspaces
PATCH	/workspaces/:id	Update workspace
DELETE	/workspaces/:id	Delete workspace

Versions (Coming Soon)

Method	Endpoint	Description
GET	/documents/:id/versions	List versions
GET	/documents/:id/versions/:v	Get version
GET	/documents/:id/versions/compare	Compare versions
POST	/documents/:id/rollback	Rollback version