API Overview

Traces provides a RESTful API for managing forensic data collections, connectors, credentials, and customers.

Base URL

https://api.traces.io/api

For local development:

http://localhost:3000/api

API Structure

/api/
├── collections/
│   ├── route.ts             # GET (list), POST (create)
│   └── [id]/
│       ├── route.ts         # GET, PATCH (pause/resume), DELETE
│       ├── files/           # GET files list
│       ├── sign-off/        # POST sign off
│       ├── download/        # GET download info
│       └── events/          # GET chain-of-custody timeline
├── connectors/
│   ├── route.ts             # GET, POST
│   ├── generate/            # POST (start generation), [id] (status), [id]/progress (SSE)
│   ├── drafts/[id]/         # draft editing + finalize
│   └── [id]/                # GET, PATCH (publish), DELETE, + versions/activate/headers/test-auth/...
├── credentials/
│   ├── route.ts             # GET (list), POST (create)
│   └── [id]/
│       ├── route.ts         # GET, DELETE (revoke)
│       └── validate/        # POST validate
└── customers/
    ├── route.ts             # GET, POST
    └── [id]/                # GET, PATCH, DELETE

note

There is no /api/auth/webhook route and no top-level /api/events/{collectionId} route. Collection timeline events are served as plain JSON from /api/collections/{id}/events (not SSE). The only Server-Sent Events stream is connector-generation progress at /api/connectors/generate/{id}/progress.

Request Format

All endpoints accept and return JSON. Include the Content-Type header for requests with a body:

Content-Type: application/json

Response Format

Successful responses return JSON with the relevant data:

{
  "id": "col_abc123",
  "status": "pending",
  "created_at": "2024-01-15T10:30:00Z"
}

List endpoints return paginated results:

{
  "data": [...],
  "total": 100,
  "limit": 20,
  "offset": 0,
  "has_more": true
}

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable error message",
    "details": {
      "field": "connector_id",
      "issue": "Connector not found"
    }
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request - validation error
401	Unauthorized - not authenticated
403	Forbidden - not authorized for this resource
404	Not Found
409	Conflict - duplicate resource
422	Unprocessable Entity - business logic error
429	Too Many Requests - rate limited
500	Internal Server Error

Rate Limiting

Rate limits are applied per user:

Role	Limit
Customer	100 requests/minute
Analyst	500 requests/minute
Admin	1000 requests/minute

Additional limits apply to specific operations:

• Collection creation: 10 per hour (Customers)

When rate limited, the API returns a 429 status with a Retry-After header.

Pagination

All list endpoints support pagination via query parameters:

Parameter	Default	Max	Description
limit	20	100	Number of items per page
offset	0	-	Number of items to skip

Filtering & Sorting

Query parameter conventions:

Pattern	Example	Description
Exact match	?status=completed	Filter by exact value
Text search	?search=slack	Full-text search
Sort field	?sort=created_at	Field to sort by
Sort order	?order=desc	asc or desc
Date range	?created_after=2024-01-01	Filter by date

Versioning

Current: The API is not versioned during MVP.

Future: URL versioning will be introduced:

• /api/v1/collections
• /api/v2/collections

Deprecation notices will be provided via response headers.