API Reference

Overview

The Conduct backend exposes a REST API with 35 endpoints for managing specs, runs, checks, features, and authentication.

Base URL

http://localhost:3000/conduct/v1

Production:

https://api.example.com/conduct/v1

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer sk_admin_xxxxxxxxxxxxx

Example:

curl -H "Authorization: Bearer sk_admin_xxx" \
  http://localhost:3000/conduct/v1/specs

API Endpoints

Specs

POST /specs - Create spec
GET /specs - List specs
GET /specs/:id - Get spec
PATCH /specs/:id - Update spec
DELETE /specs/:id - Delete spec
GET /specs/:id/runs - Get spec runs

Runs

POST /runs - Create run
GET /runs - List runs
GET /runs/:id - Get run
PATCH /runs/:id - Update run
DELETE /runs/:id - Delete run
POST /runs/:id/features - Link features

Checks

POST /checks - Create check
GET /checks - List checks
GET /checks/:id - Get check
PATCH /checks/:id - Update check
DELETE /checks/:id - Delete check

Features

GET /features - List features
GET /features/:id - Get feature
GET /features/:id/runs - Get feature runs

Auth

POST /auth/keys - Create API key
GET /auth/keys - List API keys
DELETE /auth/keys/:id - Revoke API key

Request Format

All requests use JSON:

Content-Type: application/json

Response Format

All responses return JSON:

{
  "data": {},
  "meta": {}
}

Errors:

{
  "error": "Error message",
  "code": "ERROR_CODE"
}

Pagination

List endpoints support cursor-based pagination:

GET /specs?limit=20&cursor=abc123

Response includes pagination info:

{
  "data": [...],
  "meta": {
    "hasMore": true,
    "nextCursor": "xyz789"
  }
}

Filtering

Filter by status, dates, etc:

GET /specs?status=draft
GET /runs?specId=SPEC-001
GET /checks?result=pass

Rate Limiting

Default limits:

100 requests per minute
429 status code when exceeded

Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1638360000

Error Codes

400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
409 - Conflict
422 - Validation Error
429 - Rate Limit Exceeded
500 - Internal Server Error