openapi: 3.1.0 info: title: LangWatch Agents Virtual Keys API version: 1.0.0 description: LangWatch openapi spec servers: - url: https://app.langwatch.ai security: - project_api_key: [] tags: - name: Virtual Keys paths: /api/gateway/v1/virtual-keys: get: responses: '200': description: Virtual keys for the project content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string display_prefix: type: string name: type: string description: type: - string - 'null' environment: type: string enum: - live - test status: type: string enum: - active - revoked principal_user_id: type: - string - 'null' provider_credential_ids: type: array items: type: string revision: type: string last_used_at: type: - string - 'null' created_at: type: string required: - id - display_prefix - name - description - environment - status - principal_user_id - provider_credential_ids - revision - last_used_at - created_at required: - data '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string message: type: string required: - error '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string message: type: string required: - error '422': description: Unprocessable Entity content: application/json: schema: type: object properties: error: type: string message: type: string required: - error '500': description: Internal Server Error content: application/json: schema: type: object properties: error: type: string message: type: string required: - error operationId: getApiGatewayV1Virtual-keys tags: - Virtual Keys parameters: [] summary: List virtual keys description: Returns every non-archived virtual key in the caller's project, ordered by creation time. post: responses: '201': description: Virtual key created content: application/json: schema: type: object properties: virtual_key: type: object properties: id: type: string display_prefix: type: string name: type: string description: type: - string - 'null' environment: type: string enum: - live - test status: type: string enum: - active - revoked principal_user_id: type: - string - 'null' provider_credential_ids: type: array items: type: string revision: type: string last_used_at: type: - string - 'null' created_at: type: string required: - id - display_prefix - name - description - environment - status - principal_user_id - provider_credential_ids - revision - last_used_at - created_at secret: type: string required: - virtual_key - secret '400': description: Validation error content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string required: - type - code - message required: - error '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string message: type: string required: - error '422': description: Unprocessable Entity content: application/json: schema: type: object properties: error: type: string message: type: string required: - error '500': description: Internal Server Error content: application/json: schema: type: object properties: error: type: string message: type: string required: - error operationId: postApiGatewayV1Virtual-keys tags: - Virtual Keys parameters: [] summary: Create virtual key description: Mints a new virtual key and returns the secret exactly once. The caller MUST persist the `secret` value — LangWatch stores only a hash. /api/gateway/v1/virtual-keys/{id}: get: responses: '200': description: Virtual key detail content: application/json: schema: type: object properties: virtual_key: type: object properties: id: type: string display_prefix: type: string name: type: string description: type: - string - 'null' environment: type: string enum: - live - test status: type: string enum: - active - revoked principal_user_id: type: - string - 'null' provider_credential_ids: type: array items: type: string revision: type: string last_used_at: type: - string - 'null' created_at: type: string required: - id - display_prefix - name - description - environment - status - principal_user_id - provider_credential_ids - revision - last_used_at - created_at required: - virtual_key '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string message: type: string required: - error '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string message: type: string required: - error '404': description: Not found content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string required: - type - code - message required: - error '422': description: Unprocessable Entity content: application/json: schema: type: object properties: error: type: string message: type: string required: - error '500': description: Internal Server Error content: application/json: schema: type: object properties: error: type: string message: type: string required: - error operationId: getApiGatewayV1Virtual-keysById tags: - Virtual Keys parameters: - schema: type: string in: path name: id required: true summary: Get virtual key patch: responses: '200': description: Updated content: application/json: schema: type: object properties: virtual_key: type: object properties: id: type: string display_prefix: type: string name: type: string description: type: - string - 'null' environment: type: string enum: - live - test status: type: string enum: - active - revoked principal_user_id: type: - string - 'null' provider_credential_ids: type: array items: type: string revision: type: string last_used_at: type: - string - 'null' created_at: type: string required: - id - display_prefix - name - description - environment - status - principal_user_id - provider_credential_ids - revision - last_used_at - created_at required: - virtual_key '400': description: Validation error content: application/json: schema: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string required: - type - code - message required: - error '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string message: type: string required: - error '422': description: Unprocessable Entity content: application/json: schema: type: object properties: error: type: string message: type: string required: - error '500': description: Internal Server Error content: application/json: schema: type: object properties: error: type: string message: type: string required: - error operationId: patchApiGatewayV1Virtual-keysById tags: - Virtual Keys parameters: - schema: type: string in: path name: id required: true summary: Update virtual key description: Partial update — send only the fields you want to change. `provider_credential_ids` replaces the entire fallback chain. `config` is deep-merged. /api/gateway/v1/virtual-keys/{id}/revoke: post: responses: '200': description: Revoked content: application/json: schema: type: object properties: virtual_key: type: object properties: id: type: string display_prefix: type: string name: type: string description: type: - string - 'null' environment: type: string enum: - live - test status: type: string enum: - active - revoked principal_user_id: type: - string - 'null' provider_credential_ids: type: array items: type: string revision: type: string last_used_at: type: - string - 'null' created_at: type: string required: - id - display_prefix - name - description - environment - status - principal_user_id - provider_credential_ids - revision - last_used_at - created_at required: - virtual_key '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string message: type: string required: - error '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string message: type: string required: - error '422': description: Unprocessable Entity content: application/json: schema: type: object properties: error: type: string message: type: string required: - error '500': description: Internal Server Error content: application/json: schema: type: object properties: error: type: string message: type: string required: - error operationId: postApiGatewayV1Virtual-keysByIdRevoke tags: - Virtual Keys parameters: - schema: type: string in: path name: id required: true summary: Revoke virtual key description: Marks the virtual key as revoked. Clients using it start receiving 401 within ~60s (the gateway's change-event long-poll period). /api/gateway/v1/virtual-keys/{id}/rotate: post: responses: '200': description: Rotated content: application/json: schema: type: object properties: virtual_key: type: object properties: id: type: string display_prefix: type: string name: type: string description: type: - string - 'null' environment: type: string enum: - live - test status: type: string enum: - active - revoked principal_user_id: type: - string - 'null' provider_credential_ids: type: array items: type: string revision: type: string last_used_at: type: - string - 'null' created_at: type: string required: - id - display_prefix - name - description - environment - status - principal_user_id - provider_credential_ids - revision - last_used_at - created_at secret: type: string required: - virtual_key - secret '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string message: type: string required: - error '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string message: type: string required: - error '422': description: Unprocessable Entity content: application/json: schema: type: object properties: error: type: string message: type: string required: - error '500': description: Internal Server Error content: application/json: schema: type: object properties: error: type: string message: type: string required: - error operationId: postApiGatewayV1Virtual-keysByIdRotate tags: - Virtual Keys parameters: - schema: type: string in: path name: id required: true summary: Rotate virtual key secret description: Mints a fresh secret for an existing VK. The old secret remains valid for 24h (grace window) so in-flight clients can roll over. components: securitySchemes: project_api_key: type: apiKey in: header name: X-Auth-Token description: 'Project API key for sending traces and accessing project-scoped resources. Format: sk-lw-... (no underscore). Obtain one by creating a project via the Admin API or the LangWatch UI.' admin_api_key: type: http scheme: bearer description: 'Admin API key for organization-level operations (managing projects, API keys). Create one in Settings > API Keys or via POST /api/api-keys. Format: sk-lw-{id}_{secret}.'