Typesense API Keys API

openapi: 3.1.0
info:
  title: Typesense Analytics Analytics Events API Keys API
  description: The Typesense Analytics API allows developers to track and analyze search behavior by recording click, conversion, and visit events. It provides endpoints for creating analytics rules, logging events with metadata tags, and retrieving popular queries and queries with no results. This data can be used to improve search relevance through query suggestions, curations, and understanding user search patterns.
  version: '30.1'
  contact:
    name: Typesense Support
    url: https://typesense.org/support
  license:
    name: GPL-3.0
    url: https://www.gnu.org/licenses/gpl-3.0.html
  termsOfService: https://typesense.org/terms
servers:
- url: '{protocol}://{hostname}:{port}'
  description: Typesense Server
  variables:
    protocol:
      default: http
      enum:
      - http
      - https
    hostname:
      default: localhost
    port:
      default: '8108'
security:
- api_key_header: []
tags:
- name: API Keys
  description: Create and manage API keys with fine-grained access control on a per-collection, per-action, or per-record level.
paths:
  /keys:
    get:
      operationId: listApiKeys
      summary: Retrieve Metadata For All API Keys
      description: Returns metadata about all API keys. The actual key values are not returned for security; only the value_prefix is included.
      tags:
      - API Keys
      responses:
        '200':
          description: List of API keys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeysResponse'
        '401':
          description: Unauthorized
    post:
      operationId: createApiKey
      summary: Create An API Key
      description: Creates a new API key with fine-grained access control. You can restrict access on a per-collection, per-action, per-record, or per-field level.
      tags:
      - API Keys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeySchema'
      responses:
        '201':
          description: API key created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /keys/{keyId}:
    parameters:
    - $ref: '#/components/parameters/keyId'
    get:
      operationId: getApiKey
      summary: Retrieve An API Key
      description: Retrieves metadata about a specific API key by ID. The full key value is not returned.
      tags:
      - API Keys
      responses:
        '200':
          description: API key metadata retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '401':
          description: Unauthorized
        '404':
          description: API key not found
    delete:
      operationId: deleteApiKey
      summary: Delete An API Key
      description: Deletes an API key by its numeric ID.
      tags:
      - API Keys
      responses:
        '200':
          description: API key deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
                    description: ID of the deleted key.
        '401':
          description: Unauthorized
        '404':
          description: API key not found
components:
  schemas:
    ApiKey:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Numeric ID of the API key.
        value:
          type: string
          description: Full API key value. Only returned on creation.
        value_prefix:
          type: string
          description: First few characters of the key for identification.
        description:
          type: string
          description: Human-readable description.
        actions:
          type: array
          items:
            type: string
        collections:
          type: array
          items:
            type: string
        expires_at:
          type: integer
          format: int64
    ApiKeySchema:
      type: object
      required:
      - description
      - actions
      - collections
      properties:
        value:
          type: string
          description: Custom API key value. If not provided, one is auto-generated.
        description:
          type: string
          description: Human-readable description of the key.
        actions:
          type: array
          description: Allowed actions for this key, such as documents:search, collections:create, or * for all.
          items:
            type: string
        collections:
          type: array
          description: Collections this key can access. Use * for all collections.
          items:
            type: string
        expires_at:
          type: integer
          format: int64
          description: Unix timestamp when this key expires. Set to 0 for no expiration.
    ApiKeysResponse:
      type: object
      properties:
        keys:
          type: array
          description: Array of API key metadata.
          items:
            $ref: '#/components/schemas/ApiKey'
  parameters:
    keyId:
      name: keyId
      in: path
      required: true
      description: Numeric ID of the API key.
      schema:
        type: integer
        format: int64
  securitySchemes:
    api_key_header:
      type: apiKey
      in: header
      name: X-TYPESENSE-API-KEY
      description: API key for authenticating requests to the Typesense server.
externalDocs:
  description: Typesense Analytics Documentation
  url: https://typesense.org/docs/30.1/api/analytics-query-suggestions.html