openapi: 3.0.0
info:
  title: helicone-api Agent API
  version: 1.0.0
  license:
    name: MIT
  contact: {}
servers:
- url: https://api.helicone.ai/
- url: http://localhost:8585/
tags:
- name: Agent
paths:
  /v1/agent/generate:
    post:
      operationId: Generate
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result_ChatCompletion-or-_content-string--reasoning-string--calls-any_.string_'
      tags:
      - Agent
      security:
      - api_key: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/OpenAIChatRequest'
              - properties:
                  inputs: {}
                  environment:
                    type: string
                  prompt_id:
                    type: string
                  logRequest:
                    type: boolean
                  useAIGateway:
                    type: boolean
                type: object
  /v1/agent/thread/{sessionId}/message:
    post:
      operationId: UpsertThreadMessage
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result_InAppThread.string_'
      tags:
      - Agent
      security:
      - api_key: []
      parameters:
      - in: path
        name: sessionId
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                metadata:
                  properties:
                    posthogSession:
                      type: string
                  additionalProperties: {}
                  type: object
                messages:
                  items: {}
                  type: array
              required:
              - metadata
              - messages
              type: object
  /v1/agent/thread/{sessionId}:
    delete:
      operationId: DeleteThread
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result__success-boolean_.string_'
      tags:
      - Agent
      security:
      - api_key: []
      parameters:
      - in: path
        name: sessionId
        required: true
        schema:
          type: string
    get:
      operationId: GetThread
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result_InAppThread.string_'
      tags:
      - Agent
      security:
      - api_key: []
      parameters:
      - in: path
        name: sessionId
        required: true
        schema:
          type: string
  /v1/agent/thread/{sessionId}/escalate:
    post:
      operationId: EscalateThread
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result_InAppThread.string_'
      tags:
      - Agent
      security:
      - api_key: []
      parameters:
      - in: path
        name: sessionId
        required: true
        schema:
          type: string
  /v1/agent/thread/create-and-escalate:
    post:
      operationId: CreateAndEscalateThread
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result_InAppThread.string_'
      tags:
      - Agent
      security:
      - api_key: []
      parameters: []
  /v1/agent/thread/{sessionId}/reopen:
    post:
      operationId: ReopenThread
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result_InAppThread.string_'
      tags:
      - Agent
      security:
      - api_key: []
      parameters:
      - in: path
        name: sessionId
        required: true
        schema:
          type: string
  /v1/agent/threads:
    get:
      operationId: GetAllThreads
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result_ThreadSummary-Array.string_'
      tags:
      - Agent
      security:
      - api_key: []
      parameters: []
  /v1/agent/mcp/search:
    post:
      operationId: SearchDocs
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result_string.string_'
      tags:
      - Agent
      security:
      - api_key: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                query:
                  type: string
              required:
              - query
              type: object
components:
  schemas:
    ResultSuccess_ChatCompletion-or-_content-string--reasoning-string--calls-any__:
      properties:
        data:
          anyOf:
          - $ref: '#/components/schemas/ChatCompletion'
          - properties:
              calls: {}
              reasoning:
                type: string
              content:
                type: string
            required:
            - calls
            - reasoning
            - content
            type: object
        error:
          type: number
          enum:
          - null
          nullable: true
      required:
      - data
      - error
      type: object
      additionalProperties: false
    CompletionUsage:
      description: Usage statistics for the completion request.
      properties:
        completion_tokens:
          type: number
          format: double
          description: Number of tokens in the generated completion.
        prompt_tokens:
          type: number
          format: double
          description: Number of tokens in the prompt.
        total_tokens:
          type: number
          format: double
          description: Total number of tokens used in the request (prompt + completion).
        completion_tokens_details:
          $ref: '#/components/schemas/CompletionUsage.CompletionTokensDetails'
          description: Breakdown of tokens used in a completion.
        prompt_tokens_details:
          $ref: '#/components/schemas/CompletionUsage.PromptTokensDetails'
          description: Breakdown of tokens used in the prompt.
      required:
      - completion_tokens
      - prompt_tokens
      - total_tokens
      type: object
      additionalProperties: false
    ThreadSummary:
      properties:
        id:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        escalated:
          type: boolean
        message_count:
          type: number
          format: double
        first_message:
          type: string
        last_message:
          type: string
        soft_delete:
          type: boolean
      required:
      - id
      - created_at
      - updated_at
      - escalated
      - message_count
      type: object
      additionalProperties: false
    OpenAIChatRequest:
      description: Simplified interface for the OpenAI Chat request format
      properties:
        model:
          type: string
        messages:
          items:
            properties:
              tool_calls:
                items:
                  properties:
                    type:
                      type: string
                      enum:
                      - function
                      nullable: false
                    function:
                      properties:
                        arguments:
                          type: string
                        name:
                          type: string
                      required:
                      - arguments
                      - name
                      type: object
                    id:
                      type: string
                  required:
                  - type
                  - function
                  - id
                  type: object
                type: array
              tool_call_id:
                type: string
              name:
                type: string
              content:
                anyOf:
                - type: string
                - items:
                    properties:
                      image_url:
                        properties:
                          url:
                            type: string
                        required:
                        - url
                        type: object
                      text:
                        type: string
                      type:
                        type: string
                    required:
                    - type
                    type: object
                  type: array
                nullable: true
              role:
                type: string
            required:
            - content
            - role
            type: object
          type: array
        temperature:
          type: number
          format: double
        top_p:
          type: number
          format: double
        max_tokens:
          type: number
          format: double
        max_completion_tokens:
          type: number
          format: double
        stream:
          type: boolean
        stop:
          anyOf:
          - items:
              type: string
            type: array
          - type: string
        tools:
          items:
            properties:
              function:
                properties:
                  strict:
                    type: boolean
                  parameters:
                    $ref: '#/components/schemas/Record_string.any_'
                  description:
                    type: string
                  name:
                    type: string
                required:
                - name
                type: object
              type:
                type: string
                enum:
                - function
                nullable: false
            required:
            - function
            - type
            type: object
          type: array
        tool_choice:
          anyOf:
          - properties:
              function:
                properties:
                  name:
                    type: string
                  type:
                    type: string
                    enum:
                    - function
                    nullable: false
                required:
                - name
                - type
                type: object
              type:
                type: string
            required:
            - type
            type: object
          - type: string
            enum:
            - none
            - auto
            - required
        parallel_tool_calls:
          type: boolean
        reasoning_effort:
          type: string
          enum:
          - minimal
          - low
          - medium
          - high
        verbosity:
          type: string
          enum:
          - low
          - medium
          - high
        frequency_penalty:
          type: number
          format: double
        presence_penalty:
          type: number
          format: double
        logit_bias:
          $ref: '#/components/schemas/Record_string.number_'
        logprobs:
          type: boolean
        top_logprobs:
          type: number
          format: double
        n:
          type: number
          format: double
        modalities:
          items:
            type: string
          type: array
        prediction: {}
        audio: {}
        response_format:
          properties:
            json_schema: {}
            type:
              type: string
          required:
          - type
          type: object
        seed:
          type: number
          format: double
        service_tier:
          type: string
        store:
          type: boolean
        stream_options: {}
        metadata:
          $ref: '#/components/schemas/Record_string.string_'
        user:
          type: string
        function_call:
          anyOf:
          - type: string
          - properties:
              name:
                type: string
            required:
            - name
            type: object
        functions:
          items: {}
          type: array
      type: object
      additionalProperties: false
    ChatCompletionMessage:
      description: A chat completion message generated by the model.
      properties:
        content:
          type: string
          nullable: true
          description: The contents of the message.
        refusal:
          type: string
          nullable: true
          description: The refusal message generated by the model.
        role:
          type: string
          enum:
          - assistant
          nullable: false
          description: The role of the author of this message.
        annotations:
          items:
            $ref: '#/components/schemas/ChatCompletionMessage.Annotation'
          type: array
          description: 'Annotations for the message, when applicable, as when using the

            [web search tool](https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat).'
        audio:
          allOf:
          - $ref: '#/components/schemas/ChatCompletionAudio'
          nullable: true
          description: 'If the audio output modality is requested, this object contains data about the

            audio response from the model.

            [Learn more](https://platform.openai.com/docs/guides/audio).'
        function_call:
          allOf:
          - $ref: '#/components/schemas/ChatCompletionMessage.FunctionCall'
          nullable: true
          deprecated: true
        tool_calls:
          items:
            $ref: '#/components/schemas/ChatCompletionMessageToolCall'
          type: array
          description: The tool calls generated by the model, such as function calls.
      required:
      - content
      - refusal
      - role
      type: object
      additionalProperties: false
    InAppThread:
      properties:
        id:
          type: string
        chat: {}
        user_id:
          type: string
        org_id:
          type: string
        created_at:
          type: string
          format: date-time
        escalated:
          type: boolean
        metadata: {}
        updated_at:
          type: string
          format: date-time
        soft_delete:
          type: boolean
      required:
      - id
      - chat
      - user_id
      - org_id
      - created_at
      - escalated
      - metadata
      - updated_at
      - soft_delete
      type: object
      additionalProperties: false
    ChatCompletionMessageCustomToolCall:
      description: A call to a custom tool created by the model.
      properties:
        id:
          type: string
          description: The ID of the tool call.
        custom:
          $ref: '#/components/schemas/ChatCompletionMessageCustomToolCall.Custom'
          description: The custom tool that the model called.
        type:
          type: string
          enum:
          - custom
          nullable: false
          description: The type of the tool. Always `custom`.
      required:
      - id
      - custom
      - type
      type: object
      additionalProperties: false
    ResultSuccess__success-boolean__:
      properties:
        data:
          properties:
            success:
              type: boolean
          required:
          - success
          type: object
        error:
          type: number
          enum:
          - null
          nullable: true
      required:
      - data
      - error
      type: object
      additionalProperties: false
    ChatCompletionMessage.Annotation.URLCitation:
      description: A URL citation when using web search.
      properties:
        end_index:
          type: number
          format: double
          description: The index of the last character of the URL citation in the message.
        start_index:
          type: number
          format: double
          description: The index of the first character of the URL citation in the message.
        title:
          type: string
          description: The title of the web resource.
        url:
          type: string
          description: The URL of the web resource.
      required:
      - end_index
      - start_index
      - title
      - url
      type: object
      additionalProperties: false
    ChatCompletionTokenLogprob:
      properties:
        token:
          type: string
          description: The token.
        bytes:
          items:
            type: number
            format: double
          type: array
          nullable: true
          description: 'A list of integers representing the UTF-8 bytes representation of the token.

            Useful in instances where characters are represented by multiple tokens and

            their byte representations must be combined to generate the correct text

            representation. Can be `null` if there is no bytes representation for the token.'
        logprob:
          type: number
          format: double
          description: 'The log probability of this token, if it is within the top 20 most likely

            tokens. Otherwise, the value `-9999.0` is used to signify that the token is very

            unlikely.'
        top_logprobs:
          items:
            $ref: '#/components/schemas/ChatCompletionTokenLogprob.TopLogprob'
          type: array
          description: 'List of the most likely tokens and their log probability, at this token

            position. In rare cases, there may be fewer than the number of requested

            `top_logprobs` returned.'
      required:
      - token
      - bytes
      - logprob
      - top_logprobs
      type: object
      additionalProperties: false
    Result_InAppThread.string_:
      anyOf:
      - $ref: '#/components/schemas/ResultSuccess_InAppThread_'
      - $ref: '#/components/schemas/ResultError_string_'
    ResultSuccess_InAppThread_:
      properties:
        data:
          $ref: '#/components/schemas/InAppThread'
        error:
          type: number
          enum:
          - null
          nullable: true
      required:
      - data
      - error
      type: object
      additionalProperties: false
    Result__success-boolean_.string_:
      anyOf:
      - $ref: '#/components/schemas/ResultSuccess__success-boolean__'
      - $ref: '#/components/schemas/ResultError_string_'
    Record_string.any_:
      properties: {}
      additionalProperties: {}
      type: object
      description: Construct a type with a set of properties K of type T
    ChatCompletionMessageCustomToolCall.Custom:
      description: The custom tool that the model called.
      properties:
        input:
          type: string
          description: The input for the custom tool call generated by the model.
        name:
          type: string
          description: The name of the custom tool to call.
      required:
      - input
      - name
      type: object
      additionalProperties: false
    ChatCompletionAudio:
      description: 'If the audio output modality is requested, this object contains data about the

        audio response from the model.

        [Learn more](https://platform.openai.com/docs/guides/audio).'
      properties:
        id:
          type: string
          description: Unique identifier for this audio response.
        data:
          type: string
          description: 'Base64 encoded audio bytes generated by the model, in the format specified in

            the request.'
        expires_at:
          type: number
          format: double
          description: 'The Unix timestamp (in seconds) for when this audio response will no longer be

            accessible on the server for use in multi-turn conversations.'
        transcript:
          type: string
          description: Transcript of the audio generated by the model.
      required:
      - id
      - data
      - expires_at
      - transcript
      type: object
      additionalProperties: false
    ChatCompletionMessageFunctionToolCall.Function:
      description: The function that the model called.
      properties:
        arguments:
          type: string
          description: 'The arguments to call the function with, as generated by the model in JSON

            format. Note that the model does not always generate valid JSON, and may

            hallucinate parameters not defined by your function schema. Validate the

            arguments in your code before calling your function.'
        name:
          type: string
          description: The name of the function to call.
      required:
      - arguments
      - name
      type: object
      additionalProperties: false
    Result_string.string_:
      anyOf:
      - $ref: '#/components/schemas/ResultSuccess_string_'
      - $ref: '#/components/schemas/ResultError_string_'
    ChatCompletion:
      description: 'Represents a chat completion response returned by model, based on the provided

        input.'
      properties:
        id:
          type: string
          description: A unique identifier for the chat completion.
        choices:
          items:
            $ref: '#/components/schemas/ChatCompletion.Choice'
          type: array
          description: 'A list of chat completion choices. Can be more than one if `n` is greater

            than 1.'
        created:
          type: number
          format: double
          description: The Unix timestamp (in seconds) of when the chat completion was created.
        model:
          type: string
          description: The model used for the chat completion.
        object:
          type: string
          enum:
          - chat.completion
          nullable: false
          description: The object type, which is always `chat.completion`.
        service_tier:
          type: string
          enum:
          - auto
          - default
          - flex
          - scale
          - priority
          - null
          nullable: true
          description: "Specifies the processing type used for serving the request.\n\n- If set to 'auto', then the request will be processed with the service tier\n  configured in the Project settings. Unless otherwise configured, the Project\n  will use 'default'.\n- If set to 'default', then the request will be processed with the standard\n  pricing and performance for the selected model.\n- If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or\n  'priority', then the request will be processed with the corresponding service\n  tier. [Contact sales](https://openai.com/contact-sales) to learn more about\n  Priority processing.\n- When not set, the default behavior is 'auto'.\n\nWhen the `service_tier` parameter is set, the response body will include the\n`service_tier` value based on the processing mode actually used to serve the\nrequest. This response value may be different from the value set in the\nparameter."
        system_fingerprint:
          type: string
          description: 'This fingerprint represents the backend configuration that the model runs with.


            Can be used in conjunction with the `seed` request parameter to understand when

            backend changes have been made that might impact determinism.'
        usage:
          $ref: '#/components/schemas/CompletionUsage'
          description: Usage statistics for the completion request.
      required:
      - id
      - choices
      - created
      - model
      - object
      type: object
      additionalProperties: false
    ChatCompletionMessageFunctionToolCall:
      description: A call to a function tool created by the model.
      properties:
        id:
          type: string
          description: The ID of the tool call.
        function:
          $ref: '#/components/schemas/ChatCompletionMessageFunctionToolCall.Function'
          description: The function that the model called.
        type:
          type: string
          enum:
          - function
          nullable: false
          description: The type of the tool. Currently, only `function` is supported.
      required:
      - id
      - function
      - type
      type: object
      additionalProperties: false
    ChatCompletionTokenLogprob.TopLogprob:
      properties:
        token:
          type: string
          description: The token.
        bytes:
          items:
            type: number
            format: double
          type: array
          nullable: true
          description: 'A list of integers representing the UTF-8 bytes representation of the token.

            Useful in instances where characters are represented by multiple tokens and

            their byte representations must be combined to generate the correct text

            representation. Can be `null` if there is no bytes representation for the token.'
        logprob:
          type: number
          format: double
          description: 'The log probability of this token, if it is within the top 20 most likely

            tokens. Otherwise, the value `-9999.0` is used to signify that the token is very

            unlikely.'
      required:
      - token
      - bytes
      - logprob
      type: object
      additionalProperties: false
    CompletionUsage.PromptTokensDetails:
      description: Breakdown of tokens used in the prompt.
      properties:
        audio_tokens:
          type: number
          format: double
          description: Audio input tokens present in the prompt.
        cached_tokens:
          type: number
          format: double
          description: Cached tokens present in the prompt.
      type: object
      additionalProperties: false
    ChatCompletion.Choice.Logprobs:
      description: Log probability information for the choice.
      properties:
        content:
          items:
            $ref: '#/components/schemas/ChatCompletionTokenLogprob'
          type: array
          nullable: true
          description: A list of message content tokens with log probability information.
        refusal:
          items:
            $ref: '#/components/schemas/ChatCompletionTokenLogprob'
          type: array
          nullable: true
          description: A list of message refusal tokens with log probability information.
      required:
      - content
      - refusal
      type: object
      additionalProperties: false
    ChatCompletionMessage.FunctionCall:
      properties:
        arguments:
          type: string
          description: 'The arguments to call the function with, as generated by the model in JSON

            format. Note that the model does not always generate valid JSON, and may

            hallucinate parameters not defined by your function schema. Validate the

            arguments in your code before calling your function.'
        name:
          type: string
          description: The name of the function to call.
      required:
      - arguments
      - name
      type: object
      additionalProperties: false
      deprecated: true
    Result_ThreadSummary-Array.string_:
      anyOf:
      - $ref: '#/components/schemas/ResultSuccess_ThreadSummary-Array_'
      - $ref: '#/components/schemas/ResultError_string_'
    ResultSuccess_ThreadSummary-Array_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/ThreadSummary'
          type: array
        error:
          type: number
          enum:
          - null
          nullable: true
      required:
      - data
      - error
      type: object
      additionalProperties: false
    Record_string.number_:
      properties: {}
      additionalProperties:
        type: number
        format: double
      type: object
      description: Construct a type with a set of properties K of type T
    CompletionUsage.CompletionTokensDetails:
      description: Breakdown of tokens used in a completion.
      properties:
        accepted_prediction_tokens:
          type: number
          format: double
          description: 'When using Predicted Outputs, the number of tokens in the prediction that

            appeared in the completion.'
        audio_tokens:
          type: number
          format: double
          description: Audio input tokens generated by the model.
        reasoning_tokens:
          type: number
          format: double
          description: Tokens generated by the model for reasoning.
        rejected_prediction_tokens:
          type: number
          format: double
          description: 'When using Predicted Outputs, the number of tokens in the prediction that did

            not appear in the completion. However, like reasoning tokens, these tokens are

            still counted in the total completion tokens for purposes of billing, output,

            and context window limits.'
      type: object
      additionalProperties: false
    Record_string.string_:
      properties: {}
      additionalProperties:
        type: string
      type: object
      description: Construct a type with a set of properties K of type T
    ChatCompletionMessage.Annotation:
      description: A URL citation when using web search.
      properties:
        type:
          type: string
          enum:
          - url_citation
          nullable: false
          description: The type of the URL citation. Always `url_citation`.
        url_citation:
          $ref: '#/components/schemas/ChatCompletionMessage.Annotation.URLCitation'
          description: A URL citation when using web search.
      required:
      - type
      - url_citation
      type: object
      additionalProperties: false
    Result_ChatCompletion-or-_content-string--reasoning-string--calls-any_.string_:
      anyOf:
      - $ref: '#/components/schemas/ResultSuccess_ChatCompletion-or-_content-string--reasoning-string--calls-any__'
      - $ref: '#/components/schemas/ResultError_string_'
    ChatCompletion.Choice:
      properties:
        finish_reason:
          type: string
          enum:
          - stop
          - length
          - tool_calls
          - content_filter
          - function_call
          description: 'The reason the model stopped generating tokens. This will be `stop` if the model

            hit a natural stop point or a provided stop sequence, `length` if the maximum

            number of tokens specified in the request was reached, `content_filter` if

            content was omitted due to a flag from our content filters, `tool_calls` if the

            model called a tool, or `function_call` (deprecated) if the model called a

            function.'
        index:
          type: number
          format: double
          description: The index of the choice in the list of choices.
        logprobs:
          allOf:
          - $ref: '#/components/schemas/ChatCompletion.Choice.Logprobs'
          nullable: true
          description: Log probability information for the choice.
        message:
          $ref: '#/components/schemas/ChatCompletionMessage'
          description: A chat completion message generated by the model.
      required:
      - finish_reason
      - index
      - logprobs
      - message
      type: object
      additionalProperties: false
    ResultSuccess_string_:
      properties:
        data:
          type: string
        error:
          type: number
          enum:
          - null
          nullable: true
      required:
      - data
      - error
      type: object
      additionalProperties: false
    ChatCompletionMessageToolCall:
      anyOf:
      - $ref: '#/components/schemas/ChatCompletionMessageFunctionToolCall'
      - $ref: '#/components/schemas/ChatCompletionMessageCustomToolCall'
      description: A call to a function tool created by the model.
    ResultError_string_:
      properties:
        data:
          type: number
          enum:
          - null
          nullable: true
        error:
          type: string
      required:
      - data
      - error
      type: object
      additionalProperties: false
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header
      description: 'Bearer token authentication. Format: ''Bearer YOUR_API_KEY'''