openapi: 3.0.2
info:
  title: Agent Studio API
  description: |
    The Agent Studio API lets you build and operate generative AI agents that use Algolia data, tools, and your chosen LLM provider.

    Use it to create, configure, publish, and update agents, then generate chat completions grounded in live data from your Algolia indices. You can manage LLM providers, Agent Studio tools, conversations, feedback, secret keys, user data, caching, and application settings for your AI experiences.

    ## Client libraries

    Use Algolia's API clients and libraries to reliably integrate Algolia's APIs with your apps.

    For more information, see [Algolia's ecosystem](https://www.algolia.com/doc/libraries).

    ## Base URL

    Base URL for the Agent Studio API:

    - `https://{APPLICATION_ID}.algolia.net/agent-studio`

    **All requests must use HTTPS.**

    ## Authentication

    Add these headers to authenticate requests:

    - `x-algolia-application-id`. Your Algolia application ID.
    - `x-algolia-api-key`. An API key with the necessary permissions to make the request.
      The required access control list (ACL) to make a request is listed in each endpoint's reference.

    You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account/api-keys).

    ## Request format

    Request bodies must be JSON objects.

    ## Response status and errors

    The Agent Studio API returns JSON responses. Since JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response.

    Successful responses return `2xx` statuses. Client errors return `4xx` statuses. Server errors return `5xx` statuses.
    Error responses have a `message` property with more information.

    ## Version

    The current version of the Agent Studio API is version 1, indicated by the `/1/` in each endpoint's URL.
  version: 0.1.0
components:
  securitySchemes:
    appId:
      $ref: '../common/securitySchemes.yml#/appId'
    apiKey:
      $ref: '../common/securitySchemes.yml#/apiKey'
servers:
  - url: https://{APPLICATION_ID}.algolia.net/agent-studio
    description: Agent Studio API.
    variables:
      APPLICATION_ID:
        default: EXAMPLE
        description: Your Algolia application ID.
security:
  - appId: []
    apiKey: []
tags:
  - name: Agents
    description: Manage your agents.
  - name: Allowed Domains
    description: Restrict where an agent's API key may be used.
  - name: Completions
    description: Generate completions.
  - name: Configurations
    description: Manage Agent Studio related application configurations.
  - name: Conversations
    description: View, export, and delete conversation history.
  - name: Feedback
    description: Capture user feedback on agent responses.
  - name: Internal
    description: Endpoints that are needed for internal or integration logic.
  - name: Providers
    description: Manage your LLM providers.
  - name: Secret Keys
    description: Manage secret keys used to authenticate requests.
  - name: User Data
    description: Manage end-user data associated with conversations.
x-beta: true
x-timeouts:
  browser:
    connect: 25000
    read: 25000
    write: 25000
  server:
    connect: 25000
    read: 25000
    write: 25000
paths:
  /1/agents:
    $ref: 'paths/agents/agents.yml'
  /1/agents/{agentId}:
    $ref: 'paths/agents/agent.yml'
  /1/agents/{agentId}/allowed-domains:
    $ref: 'paths/agents/agentAllowedDomains.yml'
  /1/agents/{agentId}/allowed-domains/bulk:
    $ref: 'paths/agents/allowedDomainsBulk.yml'
  /1/agents/{agentId}/allowed-domains/{domainId}:
    $ref: 'paths/agents/allowedDomain.yml'
  /1/agents/{agentId}/cache:
    $ref: 'paths/agents/agentCache.yml'
  /1/agents/{agentId}/completions:
    $ref: 'paths/agents/agentCompletions.yml'
  /1/agents/{agentId}/conversations:
    $ref: 'paths/conversations/conversations.yml'
  /1/agents/{agentId}/conversations/export:
    $ref: 'paths/conversations/conversationsExport.yml'
  /1/agents/{agentId}/conversations/{conversationId}:
    $ref: 'paths/conversations/conversation.yml'
  /1/agents/{agentId}/publish:
    $ref: 'paths/agents/agentPublish.yml'
  /1/agents/{agentId}/unpublish:
    $ref: 'paths/agents/agentUnpublish.yml'
  /1/configuration:
    $ref: 'paths/configuration/configuration.yml'
  /1/feedback:
    $ref: 'paths/feedback/feedback.yml'
  /1/providers:
    $ref: 'paths/providers/providers.yml'
  /1/providers/models:
    $ref: 'paths/providers/models.yml'
  /1/providers/{providerId}:
    $ref: 'paths/providers/provider.yml'
  /1/providers/{providerId}/models:
    $ref: 'paths/providers/providerModels.yml'
  /1/secret-keys:
    $ref: 'paths/secret-keys/secretKeys.yml'
  /1/secret-keys/{secretKeyId}:
    $ref: 'paths/secret-keys/secretKey.yml'
  /1/user-data/{userToken}:
    $ref: 'paths/user-data/userData.yml'
  /{path}:
    $ref: '../common/paths/customRequest.yml'
  /setClientApiKey:
    $ref: '../common/helpers/setClientApiKey.yml#/method'