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

# List categories

> Returns categories for a given company, or a single category by slug.

**Lookup modes:**
- By `slug` — returns the single matching category
- By `company_domain` or `company_id` — returns all categories for that company

At least one of `company_domain`, `company_id`, or `slug` is required.



## OpenAPI

````yaml GET /api/v1/categories/
openapi: 3.0.3
info:
  title: Sacra API
  version: 1.0.0
  description: >-
    The Sacra API currently supports querying News, Documents, Companies and
    Categories that enable you to use Sacra research within your own
    application.


    ## **Getting started guide**


    To start using the APIs, you need to:


    - Only available to **Platforms** and **Funds** tier members. (See
    [here](https://sacra.com/pricing/))
        
    - You must use a valid API Key to send requests to the API endpoints. You
    can generate your API key in the Api Keys section of your [Organization
    Settings](https://sacra.com/orgs/settings/general/).
        
    - The API returns request responses in JSON format. When an API request
    returns an error, it is sent in the JSON response as an error key.
        

    ## Authentication


    The Sacra API uses Tokens for authentication.


    You can generate a Sacra API Key/Token in the Api Keys section of your
    [Organization Settings](https://sacra.com/orgs/settings/general/).


    You must include an API Key/Token in each request to the Sacra API with the
    **Authorization** request header.


    ### Authentication error response


    If a Token is missing, malformed, or invalid, you will receive an HTTP 401
    Unauthorized response code.


    ### **Need some help?**


    In case you have questions, we will eventually provide tutorials and a FAQ
    page. But for now you can check out the
    [#developers](https://discord.gg/mTswyV8gg3) channel in our community
    [Discord](https://discord.gg/mTswyV8gg3), there’s a good chance our
    community has an answer for you.


    ## Authorization


    | **Key** | **Value** |

    | --- | --- |

    | Authorization | Token {{API_KEY}} |
servers:
  - url: https://sacra.com
    description: Production
security: []
tags:
  - name: Companies
  - name: Categories
  - name: Events
  - name: News
  - name: Documents
  - name: Filings
  - name: Embeds
  - name: Metrics
  - name: Funding (Legacy)
paths:
  /api/v1/categories/:
    get:
      tags:
        - Categories
      summary: List categories
      description: >-
        Returns categories for a given company, or a single category by slug.


        **Lookup modes:**

        - By `slug` — returns the single matching category

        - By `company_domain` or `company_id` — returns all categories for that
        company


        At least one of `company_domain`, `company_id`, or `slug` is required.
      operationId: categories_retrieve
      parameters:
        - in: query
          name: company_domain
          schema:
            type: string
          description: >-
            Fully qualified company domain (e.g. `figma.com`). Required if
            `company_id` and `slug` are not given.
        - in: query
          name: company_id
          schema:
            type: string
          description: >-
            Company ID (e.g. `101`). Required if `company_domain` and `slug` are
            not given.
        - in: query
          name: slug
          schema:
            type: string
          description: Category slug to look up directly (e.g. `design`).
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoriesResponse'
              examples:
                ByCompanyDomain:
                  value:
                    categories:
                      - id: 31
                        name: design
                        slug: design
                      - id: 13
                        name: b2b
                        slug: b2b
                      - id: 32
                        name: online whiteboard
                        slug: online-whiteboard
                BySlug:
                  value:
                    categories:
                      - id: 31
                        name: design
                        slug: design
          description: ''
        '400':
          content:
            text/plain:
              schema:
                type: string
                example: Ensure company_domain is a valid URL.
          description: Missing required parameter or invalid domain.
        '404':
          content:
            text/plain:
              schema:
                type: string
                example: Categories for requested company not found.
          description: Category or company not found.
      security:
        - SacraAPIAuthentication: []
components:
  schemas:
    CategoriesResponse:
      type: object
      properties:
        categories:
          type: array
          items:
            $ref: '#/components/schemas/Category'
      required:
        - categories
    Category:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        slug:
          type: string
      required:
        - id
        - name
        - slug
  securitySchemes:
    SacraAPIAuthentication:
      type: apiKey
      in: header
      name: Authorization
      description: |-
        Authenticate using one of two formats:

        - **Organization/user token:** `Token <your-token>`
        - **Stytch JWT:** `Bearer <your-jwt>`

````