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.
    The official API clients are covered by Algolia's [Service Level Agreement](https://www.algolia.com/policies/sla).

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

    ## Base URLs

    Base URLs for the Agent Studio API:

    - `https://{APPLICATION_ID}.algolia.net`
    - `https://{APPLICATION_ID}-dsn.algolia.net`.
      If your subscription includes a [Distributed Search Network](https://dashboard.algolia.com/infra),
      this ensures that requests are sent to servers closest to users.

    Both URLs provide high availability by distributing requests with load balancing.

    All Agent Studio paths are prefixed with `/agent-studio`.

    **All requests must use HTTPS.**

    ## Retry strategy

    To guarantee high availability, implement a retry strategy for all API requests using the URLs of your servers as fallbacks:

    - `https://{APPLICATION_ID}-1.algolianet.com`
    - `https://{APPLICATION_ID}-2.algolianet.com`
    - `https://{APPLICATION_ID}-3.algolianet.com`

    These URLs use a different DNS provider than the primary URLs.
    Randomize this list to ensure an even load across the three servers.

    All Algolia API clients implement this retry strategy.

    ## 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).

    ## Rate limits

    The Agent Studio API rate-limits requests.
    Responses include `X-RateLimit-Limit` and `X-RateLimit-Remaining` headers with the current limit.
    When you exceed the limit, the API returns a `429` status with a `Retry-After` header.

    ## Request format

    Request bodies must be JSON objects.

    ## Parameters

    Parameters are passed as query parameters for GET and DELETE requests,
    and in the request body for POST and PUT requests.

    Query parameters must be [URL-encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding).
    Non-ASCII characters must be UTF-8 encoded.
    Plus characters (`+`) are interpreted as spaces.

    ## 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: 1.0.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: Context
    description: Compact or trim conversation context before sending it to completions.
  - name: Conversations
    description: View, export, and delete conversation history.
  - name: Feedback
    description: Capture user feedback on agent responses.
  - name: Providers
    description: Manage your LLM providers.
  - name: Secret Keys
    description: Manage secret keys used to authenticate requests.
  - name: Tasks
    description: Run configured agent tasks.
  - name: User Data
    description: Manage end-user data associated with conversations.
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}/tasks:
    $ref: 'paths/agents/agentTasks.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/unstable/context/compact:
    $ref: 'paths/context/contextCompact.yml'
  /1/unstable/context/trim:
    $ref: 'paths/context/contextTrim.yml'
  /1/user-data/{userToken}:
    $ref: 'paths/user-data/userData.yml'
  /{path}:
    $ref: '../common/paths/customRequest.yml'
  /setClientApiKey:
    $ref: '../common/helpers/setClientApiKey.yml#/method'