openapi: 3.1.0
info:
  title: AlphaSense Agent API
  description: >-
    GraphQL surface for embedding AlphaSense market intelligence into customer
    AI agents. Wraps GenSearch (auto / fast / thinkLonger / deepResearch modes),
    Workflow Agents, and the Document Search API behind an OAuth 2.0 +
    API-key-protected /gql endpoint. Returns markdown-formatted answers with
    inline citations into the AlphaSense corpus (filings, broker research,
    Tegus expert call transcripts, news, internal Enterprise Intelligence
    documents). Documented at
    https://developer.alpha-sense.com/agent-api/quickstart.
  version: '1.0'
  contact:
    name: AlphaSense Developer Support
    url: https://developer.alpha-sense.com/
  termsOfService: https://www.alpha-sense.com/legal/
externalDocs:
  description: AlphaSense Agent API Quickstart
  url: https://developer.alpha-sense.com/agent-api/quickstart
servers:
  - url: https://api.alpha-sense.com
    description: AlphaSense SaaS API gateway
  - url: https://{customerDomain}
    description: AlphaSense Private Cloud (customer-hosted)
    variables:
      customerDomain:
        default: customer.alpha-sense.cloud
        description: Customer-provisioned Private Cloud domain.
tags:
  - name: Authentication
    description: OAuth 2.0 token exchange for the AlphaSense platform.
  - name: GenSearch
    description: Generative-search mutations and conversation polling for AlphaSense GenSearch.
  - name: Deep Research
    description: Long-horizon Deep Research agent invocations and progress polling.
  - name: Workflow Agents
    description: Pre-built and customer-defined workflow-agent invocations.
  - name: Document Search
    description: GraphQL document search across the AlphaSense corpus.
security:
  - bearerAuth: []
    apiKeyHeader: []
paths:
  /auth:
    post:
      operationId: authenticate
      summary: Exchange AlphaSense Credentials For A Bearer Token
      description: >-
        OAuth 2.0 password-grant token endpoint. Submit the user email and
        password together with the client credentials issued by AlphaSense and
        the x-api-key header. Returns a bearer token that must be sent on every
        subsequent /gql request.
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AuthTokenRequest'
      responses:
        '200':
          description: Authentication succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTokenResponse'
        '401':
          description: Authentication failed.
  /gql:
    post:
      operationId: graphqlGateway
      summary: Execute An AlphaSense GraphQL Operation
      description: >-
        Single GraphQL endpoint that fronts the AlphaSense Agent API and
        Utility APIs. Submit a query or mutation in the body; the operation
        selects the surface (GenSearch, Deep Research, Workflow Agents,
        Document Search, Companies, Brokers, Watchlist, Trends, User,
        Download). Authentication is the bearer token from /auth plus the
        x-api-key header.
      tags:
        - GenSearch
        - Deep Research
        - Workflow Agents
        - Document Search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
      responses:
        '200':
          description: GraphQL response envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphQLResponse'
        '401':
          description: Missing or invalid bearer token / API key.
        '429':
          description: Rate or credit limit exceeded.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
  schemas:
    AuthTokenRequest:
      type: object
      required:
        - grant_type
        - username
        - password
        - client_id
        - client_secret
      properties:
        grant_type:
          type: string
          enum: [password]
          description: OAuth 2.0 grant type. Must be 'password'.
        username:
          type: string
          format: email
          description: AlphaSense user email.
        password:
          type: string
          format: password
          description: AlphaSense user password.
        client_id:
          type: string
          description: OAuth client identifier issued by AlphaSense.
        client_secret:
          type: string
          format: password
          description: OAuth client secret issued by AlphaSense.
    AuthTokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: Bearer token to send on subsequent /gql calls.
        token_type:
          type: string
          enum: [Bearer]
        expires_in:
          type: integer
          description: Token lifetime in seconds.
        refresh_token:
          type: string
          description: Refresh token (if issued).
    GraphQLRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: GraphQL query or mutation document.
        variables:
          type: object
          additionalProperties: true
          description: GraphQL variables map.
        operationName:
          type: string
          description: Named operation when the document defines more than one.
    GraphQLResponse:
      type: object
      properties:
        data:
          type: object
          additionalProperties: true
          description: GraphQL response data payload.
        errors:
          type: array
          description: GraphQL errors, if any.
          items:
            $ref: '#/components/schemas/GraphQLError'
    GraphQLError:
      type: object
      properties:
        message:
          type: string
        path:
          type: array
          items:
            type: string
        extensions:
          type: object
          additionalProperties: true
    GenSearchMode:
      type: string
      enum:
        - auto
        - fast
        - thinkLonger
        - deepResearch
      description: GenSearch reasoning mode. 'deepResearch' invokes the long-horizon Deep Research agent.
    GenSearchConversation:
      type: object
      properties:
        id:
          type: string
          description: Conversation identifier returned by askGenSearch. Used for polling.
        progress:
          type: number
          minimum: 0
          maximum: 1
          description: Completion progress; 1.0 indicates the answer is ready.
        answer:
          type: string
          description: Markdown-formatted GenSearch answer.
        citations:
          type: array
          items:
            $ref: '#/components/schemas/Citation'
    Citation:
      type: object
      properties:
        documentId:
          type: string
          description: AlphaSense document identifier.
        title:
          type: string
        sourceType:
          type: string
          description: Source class (filing, broker, transcript, tegus, news, internal).
        url:
          type: string
          format: uri
        snippet:
          type: string
    WorkflowAgent:
      type: object
      properties:
        id:
          type: string
          description: Workflow agent identifier (pre-built or customer-defined).
        name:
          type: string
        description:
          type: string
        inputs:
          type: object
          additionalProperties: true
        outputs:
          type: object
          additionalProperties: true
    Document:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        releasedAt:
          type: string
          format: date-time
        sourceType:
          type: string
        companies:
          type: array
          items:
            type: string
        url:
          type: string
          format: uri