openapi: 3.1.0
info:
  title: Palantir Foundry API v2
  description: >-
    The Palantir Foundry API v2 is a REST API for interacting with Foundry
    resources such as users, groups, datasets, and ontologies. Endpoints use
    OAuth 2.0 (with Bearer tokens) and largely use JSON requests and responses.
  version: "v2"
  contact:
    name: Palantir Foundry
    url: https://www.palantir.com/docs/foundry/api/v2/general/overview/introduction/
servers:
  - url: https://{hostname}/api/v2
    description: Foundry tenant API base URL
    variables:
      hostname:
        default: foundry.example.palantirfoundry.com
        description: The hostname of your Foundry stack
security:
  - bearerAuth: []
tags:
  - name: Admin - Users
  - name: Admin - Groups
  - name: Datasets
paths:
  /admin/users:
    get:
      tags: [Admin - Users]
      summary: List users
      description: >-
        Retrieves all users from the system with support for pagination and
        filtering by user status (active or deleted).
      operationId: listUsers
      parameters:
        - in: query
          name: pageSize
          schema:
            type: integer
        - in: query
          name: pageToken
          schema:
            type: string
      responses:
        '200':
          description: A paginated list of users
        '401':
          description: Unauthorized
  /admin/groups:
    get:
      tags: [Admin - Groups]
      summary: List groups
      description: >-
        Retrieves all groups in the system with pagination support. The
        response includes group details such as name, organizations,
        description, and realm information.
      operationId: listGroups
      parameters:
        - in: query
          name: pageSize
          schema:
            type: integer
        - in: query
          name: pageToken
          schema:
            type: string
      responses:
        '200':
          description: A paginated list of groups
        '401':
          description: Unauthorized
  /datasets:
    post:
      tags: [Datasets]
      summary: Create a dataset
      description: >-
        Creates a new Dataset. A default branch — `master` for most
        enrollments — will be created on the Dataset.
      operationId: createDataset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Dataset created
        '401':
          description: Unauthorized
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        OAuth 2.0 Bearer token. The token must be passed as an `Authorization`
        header using the `Bearer` authentication scheme. Foundry supports
        user-generated API tokens (for development), Authorization Code grant,
        and Client Credentials grant.