Start Generation

Start automated connector generation from API documentation.

POST /api/connectors/generate

Authorization

• Analyst: Required

Overview

This endpoint initiates the automated connector generation process. Traces will:

1. Fetch and parse the provided API documentation
2. Identify forensically relevant endpoints
3. Use AI to analyze and categorize endpoints
4. Generate a draft connector for review

Request

Two modes are supported:

1. JSON (Content-Type: application/json) — provide a documentation URL.
2. Multipart (multipart/form-data) — upload a spec file under the file field. Platform name and base URL are derived during analysis, not supplied here.

JSON Body

Field	Type	Required	Description
documentation_url	string (url)	Yes	URL to the API documentation / spec

Request Example

{
  "documentation_url": "https://api.slack.com/methods"
}

Response

{
  "generation_id": "gen_abc123",
  "message": "Generation started"
}

Poll progress at GET /api/connectors/generate/{generation_id} or stream it at /api/connectors/generate/{generation_id}/progress.

Generation Process

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Parsing   │────▶│  Analyzing  │────▶│   Review    │────▶│  Completed  │
│             │     │   (LLM)     │     │             │     │             │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

Stages

Stage	Description
parsing	Fetching and parsing documentation
analyzing	LLM analyzing endpoints for forensic relevance
review	Draft ready for analyst review
completed	Connector finalized
failed	Error during generation

Supported Documentation Formats

Format	Auto-Detection
OpenAPI 3.x	Yes
Swagger 2.0	Yes
Postman Collection	Yes
HTML Documentation	Partial

Example Request

# JSON (URL)
curl -X POST "https://api.traces.io/api/connectors/generate" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "documentation_url": "https://api.github.com/openapi.json" }'

# Multipart (file upload)
curl -X POST "https://api.traces.io/api/connectors/generate" \
  -H "Authorization: Bearer <token>" \
  -F "file=@openapi.json"

Error Responses

400 Bad Request

Missing/invalid documentation_url, or no file in a multipart request:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": { "documentation_url": ["Must be a valid URL"] }
  }
}