openapi: 3.2.0
info:
  title: Akta Pro List Generation API
  version: 1.0.0
  contact:
    url: https://akta.pro
  description: 'Operations tagged List Generation across 2 of this provider''s published API definitions: akta-pro-docs-openapi.json, akta-pro-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.akta.pro/api
  description: Production server
tags:
- name: List Generation
  description: Build targeted company lists using structured filters or natural language queries
paths:
  /v1/list/generate/companies/:
    post:
      description: Build targeted company lists using structured filters or natural language queries, with optional data enrichment.
      operationId: generateCompanyList
      tags:
      - List Generation
      security:
      - xApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListGenerationRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListGenerationResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Generate company list
      x-summary-source: derived
    servers:
    - url: https://api.akta.pro/api
      description: Production server
  /v1/list/filter-builder/:
    post:
      description: Converts natural language queries into structured filter conditions for the List Generation API.
      operationId: translateQuery
      tags:
      - List Generation
      security:
      - xApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranslateQueryRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranslateQueryResponse'
      summary: Translate query
      x-summary-source: derived
    servers:
    - url: https://api.akta.pro/api
      description: Production server
components:
  schemas:
    TranslateQueryRequest:
      type: object
      properties:
        query:
          type: string
          description: Natural language description of target companies (e.g. 'series a companies in mumbai working in climate tech').
      required:
      - query
    ListGenerationRequest:
      type: object
      properties:
        query:
          type: string
          description: Natural language search query (e.g. 'SaaS companies in the US with Series A funding'). Cannot be used with filters.
        filters:
          type: object
          additionalProperties: true
          description: Structured filter conditions. Use the Filter Builder API to generate valid filters. Cannot be used with query. See filter options at /api-reference/listgen-api.
        sections:
          type: array
          items:
            type: string
          description: 'Data enrichment sections to include. Values: firmographic, business_model, company_assessment, trust_signal, company_hierarchy, digital_presence, financial_estimate, location, management_profile, product_offering, strategic_signal, customer_profile, industry, technology, funding_detail (Subscription, Enterprise), mna_and_investment (Subscription, Enterprise)'
        sort_by:
          type: string
          enum:
          - relevance
          - revenue_estimate
          - valuation_estimate
          - employee_range
          - total_funding
          - founded_year
          description: 'Field to sort results by. Default: relevance'
        sort_order:
          type: string
          enum:
          - asc
          - desc
          description: 'Sort direction. Default: desc'
        limit:
          type: integer
          description: 'Maximum companies to return. Default: 50, Max: 500'
        offset:
          type: integer
          description: 'Number of results to skip for pagination. Default: 0'
    TranslateQueryResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            filters:
              type: object
              description: Structured filters object equivalent to the input query, using dotted-path filter keys.
        credits_consumed:
          type: number
          format: float
    ListGenerationResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            description: Company object with identity fields (uuid, name, website) plus any requested enrichment sections.
        count:
          type: integer
          description: Number of companies returned.
        total_count:
          type: integer
          description: Total matching companies. Capped at 500.
        credits_consumed:
          type: number
          format: float
          description: Credits consumed. Returns 0 when no enrichment sections requested.
    Error:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
  securitySchemes:
    xApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key obtained from your Akta account.
externalDocs:
  description: Official Akta.pro API Documentation
  url: https://docs.akta.pro
x-refined-from:
- akta-pro-docs-openapi.json
- akta-pro-openapi.yml