> ## Documentation Index > Fetch the complete documentation index at: https://docs.talkpilot.io/llms.txt > Use this file to discover all available pages before exploring further. # Create an API key > Creates a new API key. **The raw key is returned only once in the response.** Store it securely — it cannot be retrieved again. `organization_id` is optional and sets the key's home organization; it must be one of the caller's memberships (otherwise `400`). The key's data scope at request time is resolved from the creator's memberships, not from this field. **Requires Supabase JWT authentication** (not API key auth); `dev_admin` only. ## OpenAPI ````yaml post /v1/api-keys openapi: 3.1.0 info: title: TalkPilot API version: 1.0.0 description: > The TalkPilot API allows you to programmatically manage your call center agents, employees, forwarding slots, knowledge base, and more. ## Authentication All API requests require an API key passed via the `X-API-Key` header: ``` X-API-Key: tp_live_abc123def456... ``` An API key can reach every organization its creator is a member of (see `GET /v1/organization`) and can be restricted to specific agents and permissions. Create and manage keys in the TalkPilot Dashboard under **Settings > API** (Dev-Admin only). ## Rate Limiting Default limits per API key: **60 requests/minute** and **1,000 requests/hour** (both enforced, both configurable per key). Rate limit headers are included in every response to a request authenticated with an API key (Dashboard JWT requests are not rate limited): - `X-RateLimit-Limit` — Max requests per minute - `X-RateLimit-Remaining` — Remaining requests in the current minute window - `X-RateLimit-Reset` — Unix timestamp roughly 60 seconds in the future When rate limited, the API returns `429 Too Many Requests` with `Retry-After: 60` (minute window) or `Retry-After: 3600` (hour window). ## Pagination List endpoints support pagination via query parameters: - `page` — Page number (default: 1) - `limit` — Items per page (default: 20, max: 100) Paginated responses include a `pagination` object with `page`, `limit`, `total`, and `pages`. ## Error Format All errors follow a consistent format: ```json { "error": { "code": "VALIDATION_ERROR", "message": "Human-readable description", "details": [{ "field": "name", "message": "Required" }], "request_id": "req_abc123" } } ``` contact: name: TalkPilot Support email: support@talkpilot.io license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.talkpilot.io description: Production security: - apiKey: [] tags: - name: Health description: API health and status - name: Agents description: Manage AI agent configurations - name: Workflow description: Multi-state conversation flow of an agent - name: Tools description: Manage agent tools (HTTP requests, call transfers, etc.) - name: Employees description: Manage employees linked to agents - name: Contacts description: >- Customer contacts (customer_database) per agent — the voice agent recognises callers and greets them by name or tag from here - name: Forwarding Slots description: Manage call forwarding slot assignments - name: Knowledge Base description: Manage agent knowledge base documents - name: Calls description: Read call records and transcripts - name: Organization description: Organization-level settings - name: API Keys description: Manage API keys (Dashboard JWT auth only; dev_admin) paths: /v1/api-keys: post: tags: - API Keys summary: Create an API key description: > Creates a new API key. **The raw key is returned only once in the response.** Store it securely — it cannot be retrieved again. `organization_id` is optional and sets the key's home organization; it must be one of the caller's memberships (otherwise `400`). The key's data scope at request time is resolved from the creator's memberships, not from this field. **Requires Supabase JWT authentication** (not API key auth); `dev_admin` only. operationId: createApiKey requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ApiKeyCreate' example: name: n8n Production permissions: - agents:read - agents:write - employees:read - employees:write - tools:read - tools:write rate_limit_per_minute: 60 expires_at: null responses: '201': description: API key created (raw key shown only once) content: application/json: schema: type: object properties: key: type: string description: >- The raw API key — store this securely, it will not be shown again example: tp_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 id: type: string format: uuid name: type: string permissions: type: array items: type: string allowed_agent_ids: type: - array - 'null' items: type: string format: uuid rate_limit_per_minute: type: integer rate_limit_per_hour: type: integer created_at: type: string format: date-time '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' security: - bearerAuth: [] components: schemas: ApiKeyCreate: type: object required: - name - permissions properties: name: type: string minLength: 1 maxLength: 255 permissions: type: array minItems: 1 items: $ref: '#/components/schemas/Permission' organization_id: type: string format: uuid description: >- Home organization of the key; must be one of the caller's memberships. Defaults to the profile organization allowed_agent_ids: type: - array - 'null' items: type: string format: uuid rate_limit_per_minute: type: integer minimum: 1 maximum: 600 default: 60 rate_limit_per_hour: type: integer minimum: 1 maximum: 10000 default: 1000 expires_at: type: - string - 'null' format: date-time description: Optional expiration date (null = never expires) Permission: type: string enum: - agents:read - agents:write - employees:read - employees:write - tools:read - tools:write - forwarding:read - forwarding:write - kb:read - kb:write - calls:read - organization:read - organization:write - contacts:read - contacts:write description: | Available permissions: - `agents:read` — List and view agent configurations - `agents:write` — Update agent settings - `employees:read` — List and view employees - `employees:write` — Create, update, delete employees - `tools:read` — List and view agent tools - `tools:write` — Create, update, delete tools - `forwarding:read` — List forwarding slots - `forwarding:write` — Create, update, delete forwarding slots - `kb:read` — List and view knowledge base documents - `kb:write` — Create, update, delete KB documents - `calls:read` — List and view call records - `organization:read` — View organization settings - `organization:write` — Update organization settings - `contacts:read` — List and view contacts (customer database) - `contacts:write` — Create, update, delete contacts Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string enum: - VALIDATION_ERROR - UNAUTHORIZED - FORBIDDEN - AGENT_NOT_ACCESSIBLE - NOT_FOUND - CONFLICT - RATE_LIMITED - INTERNAL_ERROR message: type: string details: type: array items: type: object properties: field: type: string message: type: string request_id: type: string responses: ValidationError: description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: VALIDATION_ERROR message: Invalid request body details: - field: llm_temperature message: Must be between 0 and 2 request_id: req_abc123 Unauthorized: description: Missing or invalid authentication content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Invalid or missing API key request_id: req_abc123 Forbidden: description: > Insufficient permissions (`FORBIDDEN`), or the agent is outside the key's `allowed_agent_ids` (`AGENT_NOT_ACCESSIBLE`) content: application/json: schema: $ref: '#/components/schemas/Error' examples: missingPermission: value: error: code: FORBIDDEN message: 'API key lacks required permission: agents:write' request_id: req_abc123 agentNotAccessible: value: error: code: AGENT_NOT_ACCESSIBLE message: API key does not have access to this agent request_id: req_abc123 securitySchemes: apiKey: type: apiKey in: header name: X-API-Key description: | API key for external access. Format: `tp_live_<32-hex-chars>`. Create keys in the TalkPilot Dashboard under Settings > API. bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Supabase JWT token (for Dashboard-only endpoints like API key management) ````