> ## Documentation Index
> Fetch the complete documentation index at: https://docs.captide.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Company Retrieval

> Identify the companies a natural-language request refers to, by name, ticker or informal reference, and return their details.

    Use it to turn free text such as "Give me Estée Lauder and Louis Vuitton" or "AAPL and MSFT" into Captide company IDs before calling other endpoints.



## OpenAPI

````yaml POST /api/v2/rag/company-retrieval
openapi: 3.1.0
info:
  title: Captide REST API
  description: >-
    API for accessing financial disclosures and AI-powered financial document
    analysis.
  version: 0.3.14
servers:
  - url: https://rest-api.captide.co
    description: Prod server
security: []
paths:
  /api/v2/rag/company-retrieval:
    post:
      tags:
        - Retrieval Augmented Generation
      summary: Retrieve companies from a query
      description: >-
        Identify the companies a natural-language request refers to, by name,
        ticker or informal reference, and return their details.

            Use it to turn free text such as "Give me Estée Lauder and Louis Vuitton" or "AAPL and MSFT" into Captide company IDs before calling other endpoints.
      operationId: company_retrieval_api_v2_rag_company_retrieval_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRequest'
              description: Natural language query to find companies
              examples:
                - query: Give me Estee Lauder and Louis Vuitton
        required: true
      responses:
        '200':
          description: Companies the query refers to
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/CompanyResponse'
                type: array
                title: Response Company Retrieval Api V2 Rag Company Retrieval Post
              example:
                - id: 081224fb-308b-41a9-ae77-6763e97191ea
                  name: LVMH Moët Hennessy Louis Vuitton SE
                  tickers:
                    - MC.PA
                  countries:
                    - FR
                  filesWithSec: false
                  permId: '4295866862'
                  listings:
                    - ticker: MC.PA
                      exchangeMic: XPAR
                      isin: FR0000121014
                - id: 20944e0e-f557-4900-a8a7-0ee88af4c898
                  name: The Estée Lauder Companies Inc.
                  tickers:
                    - EL
                  countries:
                    - US
                  filesWithSec: true
                  cik: '1001250'
                  permId: '4295903171'
                  listings:
                    - ticker: EL
                      exchangeMic: XNYS
                      isin: US5184391044
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              examples:
                missing_key:
                  summary: Missing API key
                  value:
                    detail: Missing API key
                invalid_key:
                  summary: Invalid or expired API key
                  value:
                    detail: Invalid or expired API key
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Not enough API credits for this request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                insufficient_credits:
                  summary: 'Insufficient credits. Required: 10 cents, Available: 4 cents'
                  value:
                    detail: >-
                      Insufficient credits. Required: 10 cents, Available: 4
                      cents
        '403':
          description: Your organization doesn't have access to this endpoint
          content:
            application/json:
              examples:
                forbidden:
                  summary: Access to this endpoint is not allowed for your organization
                  value:
                    detail: >-
                      Access to this endpoint is not allowed for your
                      organization
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            Validation error: a parameter or body field is missing, has the
            wrong type or is out of range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              example:
                detail:
                  - type: missing
                    loc:
                      - body
                    msg: Field required
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              examples:
                rate_limited:
                  summary: 'Rate limit exceeded: 100 requests per minute'
                  value:
                    detail: 'Rate limit exceeded: 100 requests per minute'
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              examples:
                database_error:
                  summary: Database error occurred
                  value:
                    detail: Database error occurred
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - APIKeyHeader: []
components:
  schemas:
    AgentRequest:
      properties:
        query:
          type: string
          minLength: 1
          title: Query
          description: The natural language query
        documentIds:
          anyOf:
            - type: string
            - type: 'null'
          title: Documentids
          description: >-
            Comma-separated string of document file IDs. If provided and
            non-empty, skips document and company selection and goes directly to
            retrieval.
      type: object
      required:
        - query
      title: AgentRequest
      description: Request model for agent queries.
    CompanyResponse:
      properties:
        id:
          type: string
          title: Id
          description: Unique company ID
        name:
          type: string
          title: Name
          description: Company name
        tickers:
          items:
            type: string
          type: array
          title: Tickers
          description: >-
            List of ticker symbols with exchange suffixes (e.g., 'ASML',
            'ASML.AS')
        countries:
          items:
            type: string
          type: array
          title: Countries
          description: Company's country of domicile (ISO 3166-1 alpha-2)
        filesWithSec:
          type: boolean
          title: Fileswithsec
          description: Whether the company files reports with the SEC
        cik:
          anyOf:
            - type: string
            - type: 'null'
          title: Cik
          description: Central Index Key (CIK) assigned by the SEC
        permId:
          anyOf:
            - type: string
            - type: 'null'
          title: Permid
          description: PermID (Permanent Identifier) assigned by Refinitiv
        listings:
          items:
            $ref: '#/components/schemas/CompanyListing'
          type: array
          title: Listings
          description: >-
            The company's listings: each ticker with its exchange's MIC and the
            security's ISIN
      type: object
      required:
        - id
        - name
        - tickers
        - countries
        - filesWithSec
      title: CompanyResponse
      description: Response model for single company retrieval.
    ErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
      type: object
      required:
        - detail
      title: ErrorResponse
      description: Standard error response model for all API endpoints.
    ValidationErrorResponse:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationErrorItem'
          type: array
          title: Detail
      type: object
      required:
        - detail
      title: ValidationErrorResponse
      description: '422 body: every invalid field of the request.'
    CompanyListing:
      properties:
        ticker:
          type: string
          title: Ticker
          description: Ticker with its exchange suffix, as in `tickers` (e.g. 'STO.AX')
        exchangeMic:
          anyOf:
            - type: string
            - type: 'null'
          title: Exchangemic
          description: ISO 10383 Market Identifier Code of the exchange (e.g. 'XASX')
        isin:
          anyOf:
            - type: string
            - type: 'null'
          title: Isin
          description: ISIN of the listed security, when known
      type: object
      required:
        - ticker
      title: CompanyListing
      description: 'One listing of the company: a ticker on an exchange.'
    ValidationErrorItem:
      properties:
        type:
          type: string
          title: Type
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Loc
        msg:
          type: string
          title: Msg
        input:
          anyOf:
            - {}
            - type: 'null'
          title: Input
        ctx:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Ctx
      type: object
      required:
        - type
        - loc
        - msg
      title: ValidationErrorItem
      description: One invalid field, as FastAPI reports it.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.