API Reference

The DevSpeak Public API enables third-party integrations — CLI tools, VS Code extensions, CI pipelines — to consume DevSpeak's AI-powered translation engine as a service.

Base URL:

| Environment | URL |

| ----------- | --------------------------------- |

| Production | https://www.devspeak.dev/api/v1 |

> The full OpenAPI 3.0.3 specification is available at [/openapi.json](/openapi.json).

-------- | ----------- | ---------------------------------------- |

| Production | dsk_live_ | Live requests against the production API |

| Development | dsk_test_ | Testing and development workflows |

Keys are displayed once at creation. Only the SHA-256 hash is stored server-side. If you lose your key, revoke it and generate a new one.

Available Scopes

| Scope | Description |

| ----------------- | ------------------------------------------ |

| optimize:write | Required for the POST /optimize endpoint |

| translate:write | Reserved for future translation endpoints |

| history:read | Reserved for future history read access |

---

Rate Limiting

| Scope | Limit | Window |

| --------------- | ------------ | ---------- |

| Per API key | 100 requests | 1 minute |

| Global (per IP) | 100 requests | 15 minutes |

Every response includes standard rate limit headers:

``text


RateLimit-Limit: 100
RateLimit-Remaining: 97
RateLimit-Reset: 1711296060

When exceeded, the API returns 429 Too Many Requests:

---

`Endpoints`

GET /api/v1/health

Public health check. No authentication required.

---

POST /api/v1/optimize

Transforms informal text into a formal, audience-specific technical specification using AI. This is the core endpoint.

Required scope: optimize:write

#### Request Body


| -------------------- | ------- | -------- | -------------------------------------------- |

| input | string | Yes | Text to optimize (10–10,000 characters) |

| audience | enum | Yes | Target audience for the output |

| context | enum | Yes | Technical domain context |

| format | enum | Yes | Desired output document format |

| tone | integer | Yes | Verbosity: 0 (concise) to 100 (detailed) |

| customInstructions | string | No | Additional guidance for AI (max 2,000 chars) |

#### Enum Values

Audience: Junior Dev · Senior Dev · Tech Lead · SRE · Data Engineer

Context: Backend · Frontend · Mobile · Data/ML · DevOps

Format: Technical Spec · Jira Tickets · API Design · RFC · Data Model · Prompt · Optimize

#### Success Response

#### Error Responses

Validation Error (400):

Unauthorized (401):

Forbidden (403):

---

`API Key Management`

These endpoints use JWT authentication (Authorization: Bearer ), not API key auth. They are intended for the web dashboard.

POST /api/keys

Generate a new API key.

Request Body:


| -------- | -------- | -------- | --------------------------------- |

| label | string | Yes | Human-readable name (1–100 chars) |

| scopes | string[] | Yes | Permissions to grant (min 1) |

Available scopes: optimize:write, translate:write, history:read

> Warning: The key field is returned exactly once. Store it securely. If lost, revoke and create a new key.

GET /api/keys

List all active (non-revoked) API keys. Raw key values are never returned.

DELETE /api/keys/:id

Revoke an API key. This is a soft delete — the key will no longer authenticate requests.

---

`Error Format`

All errors follow a consistent envelope:

`json


{
  "success": false,
  "error": "Human-readable error message",
  "details": []
}

| Status | Meaning |


| ------ | ---------------------------------------------- |

| 400 | Validation error — check the details array |

| 401 | Missing, invalid, or revoked API key / JWT |

| 403 | API key lacks required scopes |

| 429 | Rate limit exceeded — retry after window reset |

| 500 | Server-side error |

---

`SDKs & Integrations`

`DevSpeak CLI`

The official CLI is the fastest way to use the API from your terminal. See the [CLI Tool guide](/docs/cli-guide) for installation and usage.

`bash


devspeak optimize "Add caching for API responses" --format "RFC"

`CI/CD Integration`

Use the API in your CI pipeline to auto-generate specs from informal requirements:

title="GitHub Actions Example"


  tabs={[
    {
      label: "workflow.yml",
      language: "yaml",

code: - name: Generate Technical Spec

run: |

curl -s -X POST https://devspeak.dev/api/v1/optimize \\

-H "Content-Type: application/json" \\

-H "x-api-key: \${{ secrets.DEVSPEAK_API_KEY }}" \\

-d '{

"input": "'"$(cat requirements.md)"'",

"audience": "Senior Dev",

"context": "Backend",

"format": "Technical Spec",

"tone": 75

}' | jq -r '.data.output' > spec.md`,

]}