openapi: 3.2.0
info:
  version: 2.0.0
  x-latency-category: responsive
  x-endpoint-cost: light
  title: Telnyx Research API
  description: SIP trunking, SMS, MMS, Call Control and Telephony Data Services.
  contact:
    email: support@telnyx.com
servers:
- url: https://api.telnyx.com/v2
  description: Version 2.0.0 of the Telnyx API
security:
- bearerAuth: []
tags:
- name: Research
  description: Deep research with citations and async task polling.
paths:
  /web_search/research:
    post:
      summary: Start research task
      description: 'Starts a deep research task that runs multiple searches, reads sources, and synthesizes an answer with citations.


        ## Synchronous mode (default)


        When `background` is `false` or omitted, the request blocks until the research completes and returns the answer with citations. This can take up to 120 seconds depending on `research_effort`.


        ## Asynchronous mode


        When `background` is `true`, the request returns immediately with a `task_id` and `status: pending`. Poll `GET /web_search/research/{task_id}` to check when the research completes and retrieve the answer.'
      operationId: CreateWebSearchResearch
      tags:
      - Research
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResearchRequest'
            example:
              query: Compare the performance of RAG vs fine-tuning for domain-specific QA
              research_effort: standard
              max_sources: 20
              background: false
      responses:
        '200':
          description: 'Research response. Shape depends on `background`:


            - **Synchronous** (`background` false/unset): returns `answer` + `citations`.

            - **Asynchronous** (`background` true): returns `task_id` + `status`.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    oneOf:
                    - $ref: '#/components/schemas/ResearchResponseSync'
                    - $ref: '#/components/schemas/ResearchResponseAsync'
              examples:
                sync:
                  summary: Synchronous response (background=false)
                  value:
                    data:
                      answer: RAG and fine-tuning serve different purposes...
                      citations:
                      - url: https://arxiv.org/abs/2401.15884
                        title: Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks
                        snippet: We show that RAG models produce more factually grounded responses...
                async:
                  summary: Asynchronous response (background=true)
                  value:
                    data:
                      task_id: bf3026a5-dd57-44dd-b922-200041be3a4b
                      status: pending
        '400':
          $ref: '#/components/responses/web-search_BadRequest'
        '401':
          $ref: '#/components/responses/web-search_Unauthorized'
        '500':
          $ref: '#/components/responses/web-search_InternalServerError'
        '502':
          $ref: '#/components/responses/web-search_ProviderError'
        '504':
          $ref: '#/components/responses/ProviderTimeout'
  /web_search/research/{task_id}:
    get:
      summary: Get research task status
      description: Polls the status of a previously started asynchronous research task. When the status is `completed`, the response includes the answer and citations. When the status is `failed`, the response includes an error message.
      operationId: GetWebSearchResearchStatus
      tags:
      - Research
      parameters:
      - name: task_id
        in: path
        required: true
        description: 'The research task ID returned by `POST /web_search/research` with `background: true`.'
        schema:
          type: string
          maxLength: 200
        example: bf3026a5-dd57-44dd-b922-200041be3a4b
      responses:
        '200':
          description: Research task status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ResearchTaskStatus'
              examples:
                completed:
                  summary: Task completed
                  value:
                    data:
                      task_id: bf3026a5-dd57-44dd-b922-200041be3a4b
                      status: completed
                      answer: RAG and fine-tuning serve different purposes...
                      citations:
                      - url: https://arxiv.org/abs/2401.15884
                        title: Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks
                running:
                  summary: Task still running
                  value:
                    data:
                      task_id: bf3026a5-dd57-44dd-b922-200041be3a4b
                      status: running
                failed:
                  summary: Task failed
                  value:
                    data:
                      task_id: bf3026a5-dd57-44dd-b922-200041be3a4b
                      status: failed
                      error: Provider request failed
        '401':
          $ref: '#/components/responses/web-search_Unauthorized'
        '404':
          $ref: '#/components/responses/web-search_NotFound'
        '500':
          $ref: '#/components/responses/web-search_InternalServerError'
        '502':
          $ref: '#/components/responses/web-search_ProviderError'
components:
  schemas:
    ResearchRequest:
      type: object
      required:
      - query
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 2000
          description: The research question or topic.
          example: Compare the performance of RAG vs fine-tuning for domain-specific QA
        research_effort:
          type: string
          enum:
          - lite
          - standard
          - deep
          description: Research depth level. `lite` is fastest, `deep` is most thorough.
          example: standard
        max_sources:
          type: integer
          minimum: 1
          maximum: 50
          description: Maximum number of sources to use.
          example: 20
        background:
          type: boolean
          description: When `true`, the research runs asynchronously. The response returns a `task_id` immediately instead of waiting for the result. Poll `GET /web_search/research/{task_id}` to check status.
          example: false
    GatewayError:
      type: object
      description: Standard Telnyx JSON:API error envelope returned by the API Gateway for authentication failures (401).
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            type: object
            required:
            - code
            - title
            properties:
              code:
                type: string
                description: Telnyx error code.
              title:
                type: string
                description: Error title.
              detail:
                type: string
                description: Human-readable error detail.
              source:
                type: object
                properties:
                  pointer:
                    type: string
              meta:
                type: object
                properties:
                  url:
                    type: string
                    format: uri
    ResearchResponseSync:
      type: object
      description: Synchronous research response (when `background` is false or unset).
      required:
      - answer
      properties:
        answer:
          type: string
          description: The synthesized research answer.
          example: RAG and fine-tuning serve different purposes...
        citations:
          type: array
          items:
            $ref: '#/components/schemas/ResearchCitation'
          description: Sources cited in the answer.
    ResearchCitation:
      type: object
      required:
      - url
      - title
      properties:
        url:
          type: string
          format: uri
          description: Source URL.
        title:
          type: string
          description: Title of the source page.
        snippet:
          type: string
          description: Relevant excerpt from the source (if available).
    WebSearchError:
      type: object
      properties:
        error:
          type: object
          required:
          - message
          properties:
            message:
              type: string
              description: Human-readable error message.
            details:
              type: object
              additionalProperties: true
              description: Additional error details (e.g. validation field errors).
    ResearchTaskStatus:
      type: object
      required:
      - task_id
      - status
      properties:
        task_id:
          type: string
          description: The research task identifier.
        status:
          type: string
          enum:
          - pending
          - running
          - completed
          - failed
          description: Current status of the research task.
        answer:
          type: string
          description: The synthesized research answer (present when status is `completed`).
        citations:
          type: array
          items:
            $ref: '#/components/schemas/ResearchCitation'
          description: Sources cited in the answer (present when status is `completed`).
        error:
          type:
          - string
          - 'null'
          description: Always present in poll responses; `null` unless the task failed.
    ResearchResponseAsync:
      type: object
      description: Asynchronous research response (when `background` is true).
      required:
      - task_id
      - status
      properties:
        task_id:
          type: string
          description: Unique identifier for the research task. Use this to poll the status.
          example: bf3026a5-dd57-44dd-b922-200041be3a4b
        status:
          type: string
          enum:
          - pending
          - running
          - completed
          - failed
          description: Current status of the research task.
          example: pending
  responses:
    ProviderTimeout:
      description: The upstream search provider timed out.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WebSearchError'
          example:
            error:
              message: Provider request timed out
    web-search_InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WebSearchError'
          example:
            error:
              message: Internal server error
    web-search_NotFound:
      description: Research task not found. Returned for unknown, malformed, expired, or already-purged task IDs.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WebSearchError'
          example:
            error:
              message: Task not found
    web-search_ProviderError:
      description: The upstream search provider returned an error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WebSearchError'
          example:
            error:
              message: Provider request failed
    web-search_BadRequest:
      description: Invalid request — validation error or invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WebSearchError'
          example:
            error:
              message: Validation error
              details: {}
    web-search_Unauthorized:
      description: 'Unauthorized — missing or invalid API key.


        The API Gateway returns this response before the request reaches the backend service. The error format follows the standard Telnyx JSON:API error envelope with `errors[]`, not the backend-level `WebSearchError` shape.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GatewayError'
          example:
            errors:
            - code: '10009'
              title: Authentication failed
              detail: Could not find any usable credentials in the request.
              meta:
                url: https://developers.telnyx.com/docs/overview/errors/10009
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Telnyx API key supplied as `Authorization: Bearer <token>`. In production, auth may be validated by the API gateway and forwarded via Telnyx auth headers.'
    Payment:
      type: apiKey
      in: header
      name: Authorization
      description: 'Machine Payment Protocol credential used on paid retries, sent as `Authorization: Payment ...`. Obtained by paying a challenge returned in the `WWW-Authenticate` header of a 402 response. This is not a Telnyx API key; initial challenge requests use standard bearer authentication instead.'
    agent-memory_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    bearerAuth:
      type: http
      scheme: bearer
    branded-calling_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    collections_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Collections and results are automatically scoped to the authenticated user's organization.
    number-reputation_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    oauthClientAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
    outbound-voice-profiles_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    pronunciation-dicts_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
    rcs-registration_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
    stored-payment-transactions_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    transcriptions-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Results are automatically scoped to the authenticated user's organization.
    web-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
x-service-info:
  categories:
  - communication
  - developer-tools
  docs:
    apiReference: https://developers.telnyx.com
    homepage: https://telnyx.com
    llms: https://telnyx.com/llms.txt