REST API

Base URL: https://opensdk.ca/api

All responses follow the shape { success: boolean, data?: T, error?: { code, message } }.

Authentication

Pass your API key via the X-API-Key header. Create an API key from the dashboard.

curl -H "X-API-Key: YOUR_API_KEY" https://opensdk.ca/api/dispatch/tasks

Endpoints

`POST /api/dispatch`

Create a new SDK generation task.

From a docs URL:

curl -X POST https://opensdk.ca/api/dispatch \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.example.com/api",
    "task": "auth, list users, and delete users",
    "language": "typescript",
    "options": { "packageName": "@my-org/sdk" }
  }'

From an OpenAPI spec:

curl -X POST https://opensdk.ca/api/dispatch \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": { "openapi": "3.1.0", "info": { "title": "My API", "version": "1.0.0" }, "..." : "..." },
    "language": "typescript"
  }'

Response (201):

{
  "success": true,
  "data": {
    "taskId": "abc-123",
    "status": "queued",
    "inputType": "docs",
    "message": "Task created. Poll GET /api/dispatch/tasks/{taskId} for status."
  }
}

Field	Type	Required	Description
`url`	string	One of `url` or `spec`	Documentation URL to analyze
`spec`	object	One of `url` or `spec`	OpenAPI 3.1 spec object
`task`	string	No	Plain English description of what to build
`language`	string	No	Target language (default: `typescript`)
`options.packageName`	string	No	Custom package name
`options.version`	string	No	Package version

`GET /api/dispatch/tasks`

List all tasks with optional filtering and pagination.

curl "https://opensdk.ca/api/dispatch/tasks?status=completed&limit=10&offset=0" \
  -H "X-API-Key: YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "tasks": [{ "id": "abc-123", "status": "completed", "..." : "..." }],
    "total": 1,
    "limit": 10,
    "offset": 0
  }
}

Parameter	Type	Default	Description
`status`	string	all	Filter by status: `queued`, `analyzing`, `building`, `generating`, `completed`, `failed`
`limit`	integer	50	Max results (max 200)
`offset`	integer	0	Pagination offset

`GET /api/dispatch/tasks/:taskId`

Get a task by ID. Returns the full task including analysis, spec, and SDK when completed.

curl https://opensdk.ca/api/dispatch/tasks/abc-123 \
  -H "X-API-Key: YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "id": "abc-123",
    "status": "completed",
    "sourceUrl": "https://docs.example.com/api",
    "language": "typescript",
    "inputType": "docs",
    "createdAt": "2026-04-02T18:00:00.000Z",
    "updatedAt": "2026-04-02T18:00:05.000Z",
    "analysis": { "pagesExamined": 42, "..." : "..." },
    "spec": { "..." : "..." },
    "sdk": { "..." : "..." }
  }
}

`POST /api/dispatch/tasks/:taskId/revise`

Revise a completed task with new instructions. The task must have status completed (returns 409 otherwise).

curl -X POST https://opensdk.ca/api/dispatch/tasks/abc-123/revise \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"revision": "add a search endpoint for filtering users by email"}'

Response:

{
  "success": true,
  "data": {
    "id": "abc-123",
    "status": "completed",
    "revision": "add a search endpoint for filtering users by email",
    "..." : "..."
  }
}

`GET /api/dispatch/tasks/:taskId/export/:format`

Export a completed task. The task must have status completed (returns 409 otherwise).

curl https://opensdk.ca/api/dispatch/tasks/abc-123/export/sdk \
  -H "X-API-Key: YOUR_API_KEY"

Format	Description
`sdk`	Generated SDK files (TypeScript package)
`openapi`	OpenAPI 3.1 JSON document
`spec`	Raw API spec

Response (sdk):

{
  "success": true,
  "data": {
    "language": "typescript",
    "packageName": "@opensdk/example-api",
    "version": "1.0.0",
    "files": [
      { "path": "src/client.ts", "content": "..." },
      { "path": "src/models.ts", "content": "..." }
    ],
    "entryPoint": "src/index.ts",
    "dependencies": {}
  }
}

`GET /api/health`

Health check. No authentication required.

curl https://opensdk.ca/api/health

Response:

{
  "success": true,
  "data": {
    "status": "ok",
    "version": "0.0.1",
    "languages": ["typescript"],
    "timestamp": "2026-04-02T18:42:39.121Z"
  }
}

Credit Costs

Operation	Credits	Endpoint
Dispatch (analyze or import)	25	`POST /api/dispatch`
Revise	10	`POST /api/dispatch/tasks/:id/revise`
Export	5	`GET /api/dispatch/tasks/:id/export/:format`

Listing tasks, getting task status, and health checks are free.

Rate Limiting

100 requests per minute per API key. Returns 429 with Retry-After header when exceeded.

Error Responses

All errors follow the same envelope:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Either 'url' (string) or 'spec' (object) is required"
  }
}

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Invalid request body or parameters
`UNAUTHORIZED`	401	Missing or invalid API key
`PAYMENT_REQUIRED`	402	Insufficient credits
`NOT_FOUND`	404	Task not found
`CONFLICT`	409	Task not in required status
`RATE_LIMITED`	429	Too many requests
`PIPELINE_ERROR`	500	Internal processing error

REST API

On this page