Graph Swiss API
    • Introduction
    • Quickstart
    • Authentication
    • Base URL
    • Errors
    • Request ID
    • Conventions
    • API
      • Health
        • Liveness probe
      • Companies
        • Search companies
        • AI-powered company search
        • Get company by ID
        • Get company journal summaries
        • Get full SHAB journal texts
        • Get detailed company report
      • Persons
        • Search persons
        • Get person by ID
      • Stocks
        • List active Swiss stock symbols
        • Get real-time stock quote
        • Get current stock price
        • Get historical OHLCV data
        • Get latest end-of-day data
        • Get company profile and statistics
        • Get income statement, balance sheet, and cash flow
        • Get key executives for a stock
    • Schemas
      • StockSymbol
      • Error
      • StockQuote
      • Company
      • StockPrice
      • CompanyDetail
      • StockHistoryValue
      • Code
      • StockHistory
      • CompanyWithRelations
      • StockEod
      • CompanyListPage
      • StockProfile
      • Person
      • StockIncomeStatement
      • ShabJournal
      • StockBalanceSheet
      • PersonCompanyLink
      • StockCashFlow
      • PersonWithCompanies
      • StockFinancials
      • PersonListPage
      • StockKeyExecutive

    Authentication

    Graph Swiss API uses a single API key passed as an HTTP header. There are no OAuth flows, no tokens to refresh, and no sessions to manage.

    At a glance#

    HeaderX-API-Key
    Required onAll /api/companies/*, /api/persons/*, /api/stocks/* endpoints
    Not required on/health, /api-docs
    Example valuenrt_live_abc123...
    The scheme is declared in the OpenAPI spec as apiKeyAuth (type: apiKey, location: header, name: X-API-Key).

    Sending the key#

    curl#

    JavaScript (fetch)#

    Node.js (server-side)#

    Read the key from an environment variable. Don't hard-code it.

    Credits and rate limits#

    Every authenticated request is metered:
    1.
    The gateway validates the key and looks up the per-endpoint credit cost.
    2.
    It atomically deducts that many credits from your team's wallet.
    3.
    Successful responses include X-Credit-Cost, X-Remaining-Balance, and X-RateLimit-* headers.
    4.
    If the upstream service fails (5xx), the credits are automatically refunded — you do not pay for failed requests.
    If you run out of credits, the API returns 402 INSUFFICIENT_CREDITS. If you exceed your rate-limit window, it returns 429 RATE_LIMIT_EXCEEDED. See Errors for the full taxonomy.

    Obtaining a key#

    API keys are issued out-of-band. Contact your swissgraph administrator to request a key. There is no public signup endpoint yet.
    When you receive your key:
    Treat it as a secret. Never commit it, never embed it in client-side JavaScript, never log it.
    Rotate immediately if a key is exposed.

    Errors you may encounter#

    HTTPCodeWhat happened
    401MISSING_API_KEYThe X-API-Key header was not sent.
    401INVALID_KEY / KEY_REVOKED / KEY_EXPIREDThe key was sent but is not valid.
    402SUBSCRIPTION_REQUIRED / FEATURE_UNAVAILABLEYour plan does not cover this endpoint.
    402INSUFFICIENT_CREDITSYour wallet balance cannot cover this call.
    403SCOPE_MISMATCHThe key is valid but lacks scope for this endpoint.
    429RATE_LIMIT_EXCEEDEDToo many requests in the current window. Back off.

    Only X-API-Key is needed#

    X-API-Key is the only authentication header the API expects. You don't need to send a Bearer token, an Authorization header, or any other credential.
    Modified at 2026-05-01 06:35:25
    Previous
    Quickstart
    Next
    Base URL
    Built with