---
openapi: 3.1.0
servers:
  - url: "https://api.tensorlake.ai/"
x-sandbox-proxy-http-servers: &sandbox_proxy_http_servers
  - url: "https://{identifier}.sandbox.tensorlake.ai"
    description: Example sandbox proxy host for a specific running sandbox. For programmatic access, use the sandbox's `ingress_endpoint`.
    variables:
      identifier:
        default: example-sandbox
        description: The sandbox ID or sandbox name.
x-sandbox-proxy-ws-servers: &sandbox_proxy_ws_servers
  - url: "wss://{identifier}.sandbox.tensorlake.ai"
    description: Example sandbox proxy WebSocket host for a specific running sandbox. For programmatic access, use the sandbox's `ingress_endpoint`.
    variables:
      identifier:
        default: example-sandbox
        description: The sandbox ID or sandbox name.
info:
  title: Tensorlake API
  description: Tensorlake Cloud APIs for Sandboxes, Document Ingestion, and Serverless Workflows
  license:
    name: ""
  version: 0.1.0
security:
  - bearerAuth: []
paths:
  /documents/v2/classify:
    post:
      tags:
        - classify
      operationId: post_classify
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ClassificationRequest"
        required: true
      responses:
        "200":
          description: Created parse job details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ParseCreatedResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "422":
          description: Invalid properties in request body
          content:
            text/plain: {}
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /documents/v2/datasets:
    get:
      tags:
        - datasets
      operationId: list_datasets_v2
      parameters:
        - name: cursor
          in: query
          description: "Optional cursor for pagination.\n\nThis is a base64-encoded string representing a timestamp.\nIt is used to paginate through the results."
          required: false
          schema:
            oneOf:
              - type: "null"
              - $ref: "#/components/schemas/Cursor"
        - name: direction
          in: query
          description: "The direction of pagination.\n\nThis can be either `next` or `prev`.\n\nThe default is `next`, which means the next page of results will be\nreturned."
          required: false
          schema:
            $ref: "#/components/schemas/PaginationDirection"
        - name: limit
          in: query
          description: "The maximum number of results to return per page.\n\nThe default is 25."
          required: false
          schema:
            type: integer
            minimum: 0
        - name: status
          in: query
          description: "The status dataset to filter the results by.\n\nThis is an optional parameter that can be used to filter the results\nby the status of the dataset.\n\nThe possible values are `processing` and `idle``."
          required: false
          schema:
            oneOf:
              - type: "null"
              - $ref: "#/components/schemas/DatasetStatus"
        - name: name
          in: query
          description: "The name of the dataset to filter the results by.\n\nThis is an optional parameter that can be used to filter the results\nby the name of the dataset.\n\nBecause dataset names are not unique, this will return all datasets\nthat match the provided name."
          required: false
          schema:
            type:
              - string
              - "null"
      responses:
        "200":
          description: List of datasets retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedResult_Dataset"
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
    post:
      tags:
        - datasets
      operationId: create_dataset_v2
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DatasetCreateRequest"
        required: true
      responses:
        "200":
          description: Dataset created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DatasetCreatedResponse"
        "400":
          description: Invalid dataset creation request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "422":
          description: Invalid properties in request body
          content:
            text/plain: {}
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  "/documents/v2/datasets/{dataset_id}":
    get:
      tags:
        - datasets
      operationId: get_dataset_v2
      parameters:
        - name: dataset_id
          in: path
          description: The ID of the dataset to retrieve
          required: true
          schema:
            type: string
        - name: include_analytics
          in: query
          description: "Retrieve the dataset analytics.\n\nWhen set to `true`, the response will include the dataset's analytics\ndata. Including:\n- Number of running parsing jobs\n- Number of completed parsing jobs\n- Number of failed parsing jobs\n- Number of pending parsing jobs\n\nDefaults to `false`."
          required: false
          schema:
            type: boolean
      responses:
        "200":
          description: Dataset retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Dataset"
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Dataset not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
    put:
      tags:
        - datasets
      operationId: update_dataset_v2
      parameters:
        - name: dataset_id
          in: path
          description: The ID of the dataset to update
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DatasetUpdateRequest"
        required: true
      responses:
        "200":
          description: Dataset updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Dataset"
        "400":
          description: Invalid dataset update request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Dataset not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "422":
          description: Invalid properties in request body
          content:
            text/plain: {}
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
    delete:
      tags:
        - datasets
      operationId: delete_dataset_v2
      parameters:
        - name: dataset_id
          in: path
          description: The id of the dataset to delete
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Dataset deleted successfully
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Dataset not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  "/documents/v2/datasets/{dataset_id}/data":
    get:
      tags:
        - datasets
      operationId: get_dataset_data_v2
      parameters:
        - name: dataset_id
          in: path
          description: The id of the dataset to retrieve data for
          required: true
          schema:
            type: string
        - name: cursor
          in: query
          description: "Optional cursor for pagination.\n\nThis is a base64-encoded string representing a timestamp.\nIt is used to paginate through the results."
          required: false
          schema:
            oneOf:
              - type: "null"
              - $ref: "#/components/schemas/Cursor"
        - name: direction
          in: query
          description: "The direction of pagination.\n\nThis can be either `next` or `prev`.\n\nThe default is `next`, which means the next page of results will be\nreturned."
          required: false
          schema:
            $ref: "#/components/schemas/PaginationDirection"
        - name: limit
          in: query
          description: "The maximum number of results to return per page.\n\nThe default is 100."
          required: false
          schema:
            type: integer
            minimum: 0
        - name: status
          in: query
          description: "The status of the parse operation to filter the results by.\n\nThis is an optional parameter that can be used to filter the results\nby the status of the parse operation.\n\nThe possible values are `running` and `idle``."
          required: false
          schema:
            oneOf:
              - type: "null"
              - $ref: "#/components/schemas/ParseStatus"
        - name: parse_id
          in: query
          description: "The ID of the parse operation to filter the results by.\n\nThis is an optional parameter that can be used to filter the results\nby the ID of the parse operation.\n\nPrefer using /documents/v2/parse/{parse_id} endpoint to get the details\nof a specific parse operation instead of filtering by parse_id."
          required: false
          schema:
            type:
              - string
              - "null"
        - name: file_name
          in: query
          description: "The name of the file to filter the results by.\n\nThis is an optional parameter that can be used to filter the results\nby the name of the file associated with the parse operation."
          required: false
          schema:
            type:
              - string
              - "null"
        - name: created_after
          in: query
          description: "The date and time after which the parse operation was created.\n\nThe date should be in RFC3339 format."
          required: false
          schema:
            type:
              - string
              - "null"
        - name: created_before
          in: query
          description: "The date and time before which the parse operation was created.\n\nThe date should be in RFC3339 format."
          required: false
          schema:
            type:
              - string
              - "null"
        - name: finished_after
          in: query
          description: "The date and time after which the parse operation was finished.\n\nThe date should be in RFC3339 format."
          required: false
          schema:
            type:
              - string
              - "null"
        - name: finished_before
          in: query
          description: "The date and time before which the parse operation was finished.\n\nThe date should be in RFC3339 format."
          required: false
          schema:
            type:
              - string
              - "null"
      responses:
        "200":
          description: List of dataset jobs retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedResult_ParseResult"
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Dataset not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  "/documents/v2/datasets/{dataset_id}/parse":
    post:
      tags:
        - datasets
      operationId: parse_dataset_file_v2
      parameters:
        - name: dataset_id
          in: path
          description: The ID of the dataset to parse
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DatasetParseRequest"
        required: true
      responses:
        "200":
          description: Dataset file parsed successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DatasetParsedResponse"
        "400":
          description: Invalid dataset ingest request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Dataset not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "422":
          description: Invalid properties in request body
          content:
            text/plain: {}
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /documents/v2/edit:
    post:
      tags:
        - edit
      operationId: post_edit
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EditRequest"
        required: true
      responses:
        "200":
          description: Created edit job details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EditCreatedResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "422":
          description: Invalid properties in request body
          content:
            text/plain: {}
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /documents/v2/extract:
    post:
      tags:
        - extract
      operationId: post_extract
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExtractRequest"
        required: true
      responses:
        "200":
          description: Created parse job details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ParseCreatedResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "422":
          description: Invalid properties in request body
          content:
            text/plain: {}
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /documents/v2/files:
    get:
      tags:
        - files_v2
      operationId: list_files_v2
      parameters:
        - name: cursor
          in: query
          description: "Optional cursor for pagination.\n\nThis is a base64-encoded string representing a timestamp.\nIt is used to paginate through the results."
          required: false
          schema:
            oneOf:
              - type: "null"
              - $ref: "#/components/schemas/Cursor"
        - name: direction
          in: query
          description: "Direction of pagination.\n\nThis can be either `next` or `prev`.\n\n`next` means to get the next page of results,\nwhile `prev` means to get the previous page of results."
          required: false
          schema:
            $ref: "#/components/schemas/PaginationDirection"
        - name: limit
          in: query
          description: "Optional limit for the number of results to return.\n\nThis is a positive integer that specifies the maximum number of results\nto return. If not provided, a default value will be used."
          required: false
          schema:
            type: integer
            minimum: 0
        - name: file_name
          in: query
          description: "Optional file name to filter results by.\n\nThis is a case-sensitive substring that will be matched against the file\nnames.\n\nIf provided, only files with names containing this substring will be\nreturned."
          required: false
          schema:
            type:
              - string
              - "null"
        - name: created_after
          in: query
          description: "The date and time after which the parse operation was created.\n\nThe date should be in RFC3339 format."
          required: false
          schema:
            type:
              - string
              - "null"
        - name: created_before
          in: query
          description: "The date and time before which the parse operation was created.\n\nThe date should be in RFC3339 format."
          required: false
          schema:
            type:
              - string
              - "null"
      responses:
        "200":
          description: List of files
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedResult_FileMetadataResponse"
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "500":
          description: Something went wrong on our side. Please reach out to support@tensorlake.ai for assistance.
    put:
      tags:
        - files_v2
      operationId: put_file_v2
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file_bytes
              properties:
                labels:
                  type:
                    - object
                    - "null"
                  description: "Optional key‑value labels such as `owner=JohnDoe`\nor `{\"owner\":\"JohnDoe\",\"project\":\"Tensorlake\"}`.\nEach label goes in its **own** form‑data part."
                  additionalProperties:
                    type: string
                  propertyNames:
                    type: string
                  example:
                    owner: JohnDoe
                    project: Tensorlake
                file_bytes:
                  type: string
                  format: binary
                  description: Binary contents of the file to upload
        required: true
      responses:
        "200":
          description: File uploaded successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileCreatedResponse"
        "400":
          description: "Invalid request. This error can occur if the multipart request is missing a file, or if the upload is interrupted."
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "499":
          description: Client closed request. This error can occur if the client closes the connection before the upload is complete.
        "500":
          description: Something went wrong on our side. Please reach out to support@tensorlake.ai for assistance.
  "/documents/v2/files/{file_id}":
    delete:
      tags:
        - files_v2
      operationId: delete_file_v2
      parameters:
        - name: file_id
          in: path
          description: The public ID of the file to delete. Only files created with the V2 API will be deleted.
          required: true
          schema:
            type: string
      responses:
        "204":
          description: File deleted successfully
        "400":
          description: "Invalid request. This error can occur if the file ID is not valid, or if the file does not exist."
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "500":
          description: Something went wrong on our side. Please reach out to support@tensorlake.ai for assistance.
  "/documents/v2/files/{file_id}/metadata":
    get:
      tags:
        - files_v2
      operationId: get_file_metadata_v2
      parameters:
        - name: file_id
          in: path
          description: The public ID of the file to retrieve metadata for the file. Only files created with the V2 API will be returned.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Information about the uploaded file
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileMetadataResponse"
        "400":
          description: "Invalid request. This error can occur if the file ID is not valid, or if the file does not exist."
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "500":
          description: Something went wrong on our side. Please reach out to support@tensorlake.ai for assistance.
  /documents/v2/parse:
    get:
      tags:
        - parse
      operationId: list_parse
      parameters:
        - name: cursor
          in: query
          description: "Optional cursor for pagination.\n\nThis is a base64-encoded string representing a timestamp.\nIt is used to paginate through the results."
          required: false
          schema:
            oneOf:
              - type: "null"
              - $ref: "#/components/schemas/Cursor"
        - name: direction
          in: query
          description: "The direction of pagination.\n\nThis can be either `next` or `prev`.\n\nThe default is `next`, which means the next page of results will be"
          required: false
          schema:
            oneOf:
              - type: "null"
              - $ref: "#/components/schemas/PaginationDirection"
        - name: dataset_name
          in: query
          description: "The name of the dataset to filter the results by.\n\nThis is an optional parameter because not every parse operation is\nassociated with a dataset."
          required: false
          schema:
            type:
              - string
              - "null"
        - name: limit
          in: query
          description: "The maximum number of results to return per page.\n\nThe default is 100."
          required: false
          schema:
            type: integer
            minimum: 0
        - name: filename
          in: query
          description: "The filename to filter the results by.\n\nThis is an optional parameter that can be used to filter the results\nby the filename of the parsed document."
          required: false
          schema:
            type:
              - string
              - "null"
        - name: status
          in: query
          description: "The status of the parse operation to filter the results by.\n\nThis is an optional parameter that can be used to filter the results\nby the status of the parse operation.\n\nThe possible values are `pending`, `processing`, `failure`, and\n`successful`."
          required: false
          schema:
            oneOf:
              - type: "null"
              - $ref: "#/components/schemas/ParseStatus"
        - name: id
          in: query
          description: The ID of the parse operation to filter the results by.
          required: false
          schema:
            type:
              - string
              - "null"
        - name: created_after
          in: query
          description: "The date and time after which the parse operation was created.\n\nThe date should be in RFC3339 format."
          required: false
          schema:
            type:
              - string
              - "null"
        - name: created_before
          in: query
          description: "The date and time before which the parse operation was created.\n\nThe date should be in RFC3339 format."
          required: false
          schema:
            type:
              - string
              - "null"
        - name: finished_after
          in: query
          description: "The date and time after which the parse operation was finished.\n\nThe date should be in RFC3339 format."
          required: false
          schema:
            type:
              - string
              - "null"
        - name: finished_before
          in: query
          description: "The date and time before which the parse operation was finished.\n\nThe date should be in RFC3339 format."
          required: false
          schema:
            type:
              - string
              - "null"
      responses:
        "200":
          description: List of parse jobs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedResult_ParseResult"
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "422":
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
    post:
      tags:
        - parse
      operationId: post_parse
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ParseRequest"
        required: true
      responses:
        "200":
          description: Created parse job details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ParseCreatedResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "422":
          description: Invalid properties in request body
          content:
            text/plain: {}
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  "/documents/v2/parse/{parse_id}":
    get:
      tags:
        - parse
      operationId: get_parse
      parameters:
        - name: parse_id
          in: path
          description: The public ID of the parse job
          required: true
          schema:
            type: string
        - name: with_options
          in: query
          required: false
          schema:
            type: boolean
      responses:
        "200":
          description: Parse result details (JSON) or progress stream (SSE)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ParseResult"
            text/event-stream:
              schema:
                type: string
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Parse job not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
    delete:
      tags:
        - parse
      operationId: delete_parse
      parameters:
        - name: parse_id
          in: path
          description: The public ID of the parse job
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Parse job deleted successfully
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Parse job not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /documents/v2/read:
    post:
      tags:
        - read
      operationId: post_read
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReadRequest"
        required: true
      responses:
        "200":
          description: Created parse job details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ParseCreatedResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "422":
          description: Invalid properties in request body
          content:
            text/plain: {}
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /sandboxes:
    post:
      tags:
        - sandboxes
      summary: Create a sandbox
      description: Create an ephemeral or named sandbox.
      operationId: create_sandbox
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSandboxRequest"
        required: true
      responses:
        "200":
          description: Sandbox created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateSandboxResponse"
        "400":
          description: Invalid sandbox creation request
          content:
            text/plain: {}
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Referenced snapshot was not found
          content:
            text/plain: {}
        "409":
          description: A sandbox with the requested name already exists in this namespace
          content:
            text/plain: {}
        "422":
          description: Invalid properties in request body
          content:
            text/plain: {}
        "500":
          description: Internal server error
          content:
            text/plain: {}
    get:
      tags:
        - sandboxes
      summary: List sandboxes
      description: List sandboxes that have not terminated. Use GET /archived-sandboxes to list terminated sandboxes within the retention window (48 hours by default).
      operationId: list_sandboxes
      parameters:
        - name: limit
          in: query
          description: Maximum number of sandboxes to return. Defaults to 100.
          required: false
          schema:
            type: integer
            minimum: 1
        - name: cursor
          in: query
          description: Base64-encoded pagination cursor returned by a previous list call.
          required: false
          schema:
            $ref: "#/components/schemas/Cursor"
        - name: direction
          in: query
          description: Pagination direction for the provided cursor.
          required: false
          schema:
            $ref: "#/components/schemas/SandboxCursorDirection"
        - name: status
          in: query
          description: Optional sandbox status filter. `running` returns running sandboxes; `suspended` returns fully suspended sandboxes, excluding those still suspending. Omit the filter to include all non-terminated states. To list terminated sandboxes, use GET /archived-sandboxes.
          required: false
          schema:
            $ref: "#/components/schemas/SandboxListStatusFilter"
      responses:
        "200":
          description: List of sandboxes retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListSandboxesResponse"
        "400":
          description: Invalid query parameters
          content:
            text/plain: {}
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "500":
          description: Internal server error
          content:
            text/plain: {}
  /sandboxes/{sandbox_id}:
    parameters:
      - name: sandbox_id
        in: path
        description: The ID of the sandbox.
        required: true
        schema:
          type: string
    get:
      tags:
        - sandboxes
      summary: Get a sandbox
      description: Retrieve metadata for a sandbox in the current project, including its `ingress_endpoint`, the base ingress origin for the sandbox's current placement, and its `sandbox_url`, the sandbox-specific management URL derived from it.
      operationId: get_sandbox
      responses:
        "200":
          description: Sandbox retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxInfo"
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Sandbox not found
          content:
            text/plain: {}
        "500":
          description: Internal server error
          content:
            text/plain: {}
    patch:
      tags:
        - sandboxes
      summary: Update a sandbox
      description: Update proxy-visible sandbox settings such as public exposed ports and whether ingress can skip authentication checks.
      operationId: update_sandbox
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchSandboxRequest"
        required: true
      responses:
        "200":
          description: Sandbox updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxInfo"
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Sandbox not found
          content:
            text/plain: {}
        "409":
          description: Sandbox is terminated and cannot be updated
          content:
            text/plain: {}
        "422":
          description: Invalid properties in request body
          content:
            text/plain: {}
        "500":
          description: Internal server error
          content:
            text/plain: {}
    delete:
      tags:
        - sandboxes
      summary: Delete a sandbox
      description: Terminate a sandbox. This operation is idempotent and returns success if the sandbox was already terminated.
      operationId: delete_sandbox
      responses:
        "200":
          description: Sandbox terminated successfully
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Sandbox not found
          content:
            text/plain: {}
        "500":
          description: Internal server error
          content:
            text/plain: {}
  /sandboxes/{sandbox_id}/snapshot:
    parameters:
      - name: sandbox_id
        in: path
        description: The ID of the sandbox.
        required: true
        schema:
          type: string
    post:
      tags:
        - sandboxes
      summary: Snapshot a sandbox
      description: Create a snapshot of a running sandbox so you can restore the same filesystem and memory state later.
      operationId: snapshot_sandbox
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                snapshot_type:
                  type: string
                  description: Snapshot type. `memory` captures filesystem, memory, and running process state for warm restore. `filesystem` captures filesystem state only for cold-boot restore. When omitted, the server default is `filesystem`.
                  enum:
                    - memory
                    - filesystem
      responses:
        "202":
          description: Snapshot creation initiated
          content:
            application/json:
              schema:
                type: object
                required:
                  - snapshot_id
                  - status
                properties:
                  snapshot_id:
                    type: string
                  status:
                    type: string
        "400":
          description: Invalid snapshot request
          content:
            text/plain: {}
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Sandbox not found
          content:
            text/plain: {}
        "500":
          description: Internal server error
          content:
            text/plain: {}
  /sandboxes/{sandbox_id}/copy:
    parameters:
      - name: sandbox_id
        in: path
        description: The running or suspended source sandbox ID or name.
        required: true
        schema:
          type: string
    post:
      tags:
        - sandboxes
      summary: Copy a sandbox
      description: >-
        Boot one or more new sandboxes from a running or suspended source,
        restoring filesystem, memory, and running processes so each copy
        warm-starts. A running source is copied from the executor hosting it; a
        suspended source is copied from the snapshot its suspend produced.
        Copies inherit the source's image, resources, entrypoint, network
        policy, and exposed ports. Takes no request body.
      operationId: copy_sandbox
      parameters:
        - name: times
          in: query
          description: Number of copies to create from the source sandbox. Defaults to 1.
          required: false
          schema:
            type: integer
            minimum: 1
        - name: name
          in: query
          description: >-
            Name for the copies. Used verbatim when `times` is 1, and suffixed
            `-1`..`-N` when it is greater, since sandbox names are unique per
            namespace. When omitted, a named source produces
            `<source-name>-copy` (suffixed the same way) and an unnamed source
            produces unnamed copies. Named copies can be suspended and resumed;
            unnamed ones terminate at their idle timeout.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: All requested sandbox copies are running
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CopySandboxResponse"
        "400":
          description: >-
            Invalid request, the source sandbox is neither running nor
            suspended, or a derived copy name is malformed or exceeds the
            63-character limit
          content:
            text/plain: {}
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Source sandbox not found
          content:
            text/plain: {}
        "409":
          description: >-
            A derived copy name is already claimed by a live sandbox in the
            namespace. Rejected before any copy is created.
          content:
            text/plain: {}
        "422":
          description: One or more copies failed before becoming ready
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CopySandboxResponse"
        "500":
          description: Internal server error
          content:
            text/plain: {}
        "504":
          description: One or more copies did not become ready within the timeout
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CopySandboxResponse"
  /sandboxes/{sandbox_id}/suspend:
    parameters:
      - name: sandbox_id
        in: path
        description: The sandbox ID or sandbox name.
        required: true
        schema:
          type: string
    post:
      tags:
        - sandboxes
      summary: Suspend a sandbox
      description: Suspend a named running sandbox by snapshotting it and terminating the live container. Returns `202 Accepted` when suspension begins or is already in progress, and `200 OK` when the sandbox is already suspended.
      operationId: suspend_sandbox
      responses:
        "200":
          description: Sandbox was already suspended
        "202":
          description: Suspend initiated
        "400":
          description: Sandbox cannot be suspended in its current state, or the sandbox is ephemeral
          content:
            text/plain: {}
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Sandbox not found
          content:
            text/plain: {}
        "500":
          description: Internal server error
          content:
            text/plain: {}
  /sandboxes/{sandbox_id}/resume:
    parameters:
      - name: sandbox_id
        in: path
        description: The sandbox ID or sandbox name.
        required: true
        schema:
          type: string
    post:
      tags:
        - sandboxes
      summary: Resume a sandbox
      description: Resume a suspended named sandbox from its suspend snapshot. Returns `202 Accepted` when resume begins and `200 OK` when the sandbox is already running.
      operationId: resume_sandbox
      responses:
        "200":
          description: Sandbox was already running
        "202":
          description: Resume initiated
        "400":
          description: Sandbox cannot be resumed in its current state, or the suspend snapshot is not ready
          content:
            text/plain: {}
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Sandbox not found
          content:
            text/plain: {}
        "500":
          description: Internal server error
          content:
            text/plain: {}
  /sandboxes/{sandbox_id}/restart:
    parameters:
      - name: sandbox_id
        in: path
        description: The sandbox ID or sandbox name.
        required: true
        schema:
          type: string
    post:
      tags:
        - sandboxes
      summary: Restart a sandbox
      description: Restart a terminated sandbox under its original ID and name. The sandbox restores from its most recent usable snapshot when one exists, and cold boots from its image otherwise. Terminated sandboxes stay restartable for 48 hours after termination. Returns `202 Accepted` when restart begins.
      operationId: restart_sandbox
      responses:
        "202":
          description: Restart initiated
        "400":
          description: Sandbox is not terminated, or the namespace is at capacity
          content:
            text/plain: {}
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Sandbox not found
          content:
            text/plain: {}
        "409":
          description: Conflict. A new sandbox has claimed this name since termination, or the restore snapshot is being deleted
          content:
            text/plain: {}
        "500":
          description: Internal server error
          content:
            text/plain: {}
  /sandboxes/{sandbox_id}/file_systems:
    parameters:
      - name: sandbox_id
        in: path
        description: The sandbox ID or sandbox name.
        required: true
        schema:
          type: string
    post:
      tags:
        - sandboxes
      summary: Attach a filesystem
      description: Attach a filesystem to a running sandbox at an absolute guest mount path. Returns `200 OK` once the mount is persisted; the mount applies asynchronously on the live sandbox. If the mount later cannot converge — including a `file_system_id` that does not exist, or a pinned `snapshot_id` that is not a permanent snapshot of the filesystem — the sandbox is terminated fail-closed with `termination_reason` and `error_details` on the sandbox object, so verify the filesystem exists (for example with `tl fs ls`) and the snapshot is listed by `tl fs history` before attaching.
      operationId: attach_file_system
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FileSystemMount"
        required: true
      responses:
        "200":
          description: Filesystem attach accepted and persisted; the returned sandbox already reflects the new `file_systems` entry
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxInfo"
        "400":
          description: Invalid mount (including `snapshot_id` without `read_only`), or the sandbox runs on an executor fleet without filesystem or snapshot-pin support
          content:
            text/plain: {}
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Sandbox not found
          content:
            text/plain: {}
        "409":
          description: Sandbox not running, mount path already in use or at the mount cap, or the sandbox's executor is momentarily unresolvable (transient — retry shortly)
          content:
            text/plain: {}
        "500":
          description: Internal server error
          content:
            text/plain: {}
    delete:
      tags:
        - sandboxes
      summary: Detach a filesystem
      description: Detach the filesystem mounted at a guest path from a running sandbox. Returns `200 OK` once the removal is persisted; the unmount applies asynchronously on the live sandbox.
      operationId: detach_file_system
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DetachFileSystemRequest"
        required: true
      responses:
        "200":
          description: Filesystem detach accepted and persisted; the returned sandbox no longer lists the `file_systems` entry
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxInfo"
        "400":
          description: Invalid mount path
          content:
            text/plain: {}
        "401":
          description: Unauthorized. Invalid or missing credentials
        "403":
          description: Forbidden. You do not have permission to access this resource
        "404":
          description: Sandbox not found, or no filesystem is mounted at the given path
          content:
            text/plain: {}
        "409":
          description: Sandbox is not running
          content:
            text/plain: {}
        "500":
          description: Internal server error
          content:
            text/plain: {}
  /api/v1/health:
    servers: *sandbox_proxy_http_servers
    get:
      tags:
        - sandbox-runtime
      summary: Runtime health
      description: Check whether the sandbox daemon is healthy.
      operationId: sandbox_runtime_health
      responses:
        "200":
          description: Sandbox daemon health
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxRuntimeHealth"
  /api/v1/info:
    servers: *sandbox_proxy_http_servers
    get:
      tags:
        - sandbox-runtime
      summary: Runtime info
      description: Retrieve sandbox daemon version, uptime, and process counts.
      operationId: sandbox_runtime_info
      responses:
        "200":
          description: Sandbox daemon metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxRuntimeInfo"
  /api/v1/processes:
    servers: *sandbox_proxy_http_servers
    post:
      tags:
        - sandbox-processes
      summary: Start a process
      description: Start a new process through the sandbox proxy, for example on `https://<sandbox-id-or-name>.sandbox.tensorlake.ai`.
      operationId: sandbox_process_start
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SandboxProcessStartRequest"
      responses:
        "201":
          description: Process created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProcessInfo"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
    get:
      tags:
        - sandbox-processes
      summary: List processes
      description: List the processes tracked inside a sandbox through the sandbox proxy.
      operationId: sandbox_process_list
      responses:
        "200":
          description: List of processes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProcessListResponse"
  /api/v1/processes/run:
    servers: *sandbox_proxy_http_servers
    post:
      tags:
        - sandbox-processes
      summary: Run a process
      description: Start a non-interactive process, stream captured output over Server-Sent Events, and emit a final exit event. Stdin is closed for this endpoint.
      operationId: sandbox_process_run
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SandboxRunProcessRequest"
      responses:
        "200":
          description: Process event stream
          content:
            text/event-stream:
              schema:
                $ref: "#/components/schemas/SandboxRunProcessEvent"
              examples:
                started:
                  summary: Process started
                  value: "data: {\"handle\":1,\"pid\":42,\"started_at\":1710000000000}\n\n"
                output:
                  summary: Process output
                  value: "data: {\"line\":\"hello\",\"timestamp\":1710000000010,\"stream\":\"stdout\"}\n\n"
                exited:
                  summary: Process exited
                  value: "data: {\"exit_code\":0}\n\n"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
  /api/v1/processes/{pid}:
    servers: *sandbox_proxy_http_servers
    parameters:
      - name: pid
        in: path
        description: The operating system PID of the process.
        required: true
        schema:
          type: integer
          format: int32
    get:
      tags:
        - sandbox-processes
      summary: Get a process
      description: Retrieve process metadata and current status for a sandbox process.
      operationId: sandbox_process_get
      responses:
        "200":
          description: Process metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProcessInfo"
        "404":
          description: Process not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
    delete:
      tags:
        - sandbox-processes
      summary: Kill a process
      description: Force-terminate a process with `SIGKILL`.
      operationId: sandbox_process_kill
      responses:
        "204":
          description: Process terminated
        "404":
          description: Process not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
  /api/v1/processes/{pid}/signal:
    servers: *sandbox_proxy_http_servers
    parameters:
      - name: pid
        in: path
        description: The operating system PID of the process.
        required: true
        schema:
          type: integer
          format: int32
    post:
      tags:
        - sandbox-processes
      summary: Send a signal
      description: Send a POSIX signal such as `SIGTERM` or `SIGKILL` to a running process.
      operationId: sandbox_process_signal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SandboxProcessSignalRequest"
      responses:
        "200":
          description: Signal delivered successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProcessSignalResponse"
        "400":
          description: Invalid signal or process is not running
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
        "404":
          description: Process not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
  /api/v1/processes/{pid}/stdin:
    servers: *sandbox_proxy_http_servers
    parameters:
      - name: pid
        in: path
        description: The operating system PID of the process.
        required: true
        schema:
          type: integer
          format: int32
    post:
      tags:
        - sandbox-processes
      summary: Write to stdin
      description: Write raw bytes to a process whose stdin was opened in `pipe` mode.
      operationId: sandbox_process_stdin
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        "204":
          description: Stdin bytes accepted
        "400":
          description: Stdin is not writable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
        "404":
          description: Process not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
  /api/v1/processes/{pid}/stdin/close:
    servers: *sandbox_proxy_http_servers
    parameters:
      - name: pid
        in: path
        description: The operating system PID of the process.
        required: true
        schema:
          type: integer
          format: int32
    post:
      tags:
        - sandbox-processes
      summary: Close stdin
      description: Close a process stdin pipe and deliver EOF to the process.
      operationId: sandbox_process_stdin_close
      responses:
        "204":
          description: Stdin closed
        "400":
          description: Stdin is not writable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
        "404":
          description: Process not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
  /api/v1/processes/{pid}/stdout:
    servers: *sandbox_proxy_http_servers
    parameters:
      - name: pid
        in: path
        description: The operating system PID of the process.
        required: true
        schema:
          type: integer
          format: int32
    get:
      tags:
        - sandbox-processes
      summary: Get stdout
      description: Read the captured stdout lines for a process.
      operationId: sandbox_process_stdout
      responses:
        "200":
          description: Captured stdout
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProcessOutputResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
  /api/v1/processes/{pid}/stderr:
    servers: *sandbox_proxy_http_servers
    parameters:
      - name: pid
        in: path
        description: The operating system PID of the process.
        required: true
        schema:
          type: integer
          format: int32
    get:
      tags:
        - sandbox-processes
      summary: Get stderr
      description: Read the captured stderr lines for a process.
      operationId: sandbox_process_stderr
      responses:
        "200":
          description: Captured stderr
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProcessOutputResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
  /api/v1/processes/{pid}/output:
    servers: *sandbox_proxy_http_servers
    parameters:
      - name: pid
        in: path
        description: The operating system PID of the process.
        required: true
        schema:
          type: integer
          format: int32
    get:
      tags:
        - sandbox-processes
      summary: Get combined process output
      description: Read the captured combined output for a process.
      operationId: sandbox_process_output
      responses:
        "200":
          description: Captured output
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProcessOutputResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
  /api/v1/processes/{pid}/output/follow:
    servers: *sandbox_proxy_http_servers
    parameters:
      - name: pid
        in: path
        description: The operating system PID of the process.
        required: true
        schema:
          type: integer
          format: int32
    get:
      tags:
        - sandbox-processes
      summary: Follow combined process output
      description: Replay captured output and follow live combined output over Server-Sent Events.
      operationId: sandbox_process_output_follow
      responses:
        "200":
          description: Output event stream
          content:
            text/event-stream:
              schema:
                type: string
  /api/v1/processes/{pid}/stdout/follow:
    servers: *sandbox_proxy_http_servers
    parameters:
      - name: pid
        in: path
        description: The operating system PID of the process.
        required: true
        schema:
          type: integer
          format: int32
    get:
      tags:
        - sandbox-processes
      summary: Follow stdout
      description: Replay captured stdout and follow live stdout over Server-Sent Events.
      operationId: sandbox_process_stdout_follow
      responses:
        "200":
          description: Stdout event stream
          content:
            text/event-stream:
              schema:
                type: string
  /api/v1/processes/{pid}/stderr/follow:
    servers: *sandbox_proxy_http_servers
    parameters:
      - name: pid
        in: path
        description: The operating system PID of the process.
        required: true
        schema:
          type: integer
          format: int32
    get:
      tags:
        - sandbox-processes
      summary: Follow stderr
      description: Replay captured stderr and follow live stderr over Server-Sent Events.
      operationId: sandbox_process_stderr_follow
      responses:
        "200":
          description: Stderr event stream
          content:
            text/event-stream:
              schema:
                type: string
  /api/v1/pty:
    servers: *sandbox_proxy_http_servers
    post:
      tags:
        - sandbox-pty
      summary: Create a PTY session
      description: Create a PTY-backed interactive terminal session through the sandbox proxy.
      operationId: sandbox_pty_create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SandboxPtyCreateRequest"
      responses:
        "201":
          description: PTY session created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxPtyCreateResponse"
        "429":
          description: Too many concurrent PTY sessions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
    get:
      tags:
        - sandbox-pty
      summary: List PTY sessions
      description: List the PTY sessions tracked inside a sandbox.
      operationId: sandbox_pty_list
      responses:
        "200":
          description: List of PTY sessions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxPtyListResponse"
  /api/v1/pty/{session_id}:
    servers: *sandbox_proxy_http_servers
    parameters:
      - name: session_id
        in: path
        description: The PTY session identifier.
        required: true
        schema:
          type: string
    get:
      tags:
        - sandbox-pty
      summary: Get a PTY session
      description: Retrieve metadata for a single PTY session.
      operationId: sandbox_pty_get
      responses:
        "200":
          description: PTY session metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxPtySessionInfo"
        "404":
          description: PTY session not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
    delete:
      tags:
        - sandbox-pty
      summary: Kill a PTY session
      description: Terminate a PTY session.
      operationId: sandbox_pty_kill
      responses:
        "204":
          description: PTY session terminated
        "404":
          description: PTY session not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
  /api/v1/pty/{session_id}/resize:
    servers: *sandbox_proxy_http_servers
    parameters:
      - name: session_id
        in: path
        description: The PTY session identifier.
        required: true
        schema:
          type: string
    post:
      tags:
        - sandbox-pty
      summary: Resize a PTY session
      description: Resize the terminal dimensions for a PTY session.
      operationId: sandbox_pty_resize
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SandboxPtyResizeRequest"
      responses:
        "204":
          description: PTY session resized
        "404":
          description: PTY session not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
  /api/v1/pty/{session_id}/ws:
    servers: *sandbox_proxy_ws_servers
    parameters:
      - name: session_id
        in: path
        description: The PTY session identifier.
        required: true
        schema:
          type: string
      - name: token
        in: query
        description: Optional PTY token. Prefer the `X-PTY-Token` header instead of the query string.
        required: false
        schema:
          type: string
      - name: X-PTY-Token
        in: header
        description: Preferred PTY session token header for WebSocket authentication.
        required: false
        schema:
          type: string
    get:
      tags:
        - sandbox-pty
      summary: Attach to a PTY session over WebSocket
      description: Upgrade to a WebSocket connection for an interactive PTY session.
      operationId: sandbox_pty_websocket
      responses:
        "101":
          description: WebSocket upgrade successful
        "403":
          description: Invalid PTY token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
        "404":
          description: PTY session not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
  /api/v1/tunnels/tcp:
    servers: *sandbox_proxy_ws_servers
    parameters:
      - name: port
        in: query
        description: Sandbox-local TCP port to connect to on 127.0.0.1.
        required: true
        schema:
          type: integer
          minimum: 1
          maximum: 65535
    get:
      tags:
        - sandbox-tunnels
      summary: Open a TCP tunnel WebSocket
      description: Upgrade to a WebSocket that relays binary frames to and from a sandbox-local TCP port.
      operationId: sandbox_tcp_tunnel
      responses:
        "101":
          description: WebSocket upgrade successful
        "400":
          description: Missing or invalid port
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
        "401":
          description: Authenticated sandbox-proxy forwarding is required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
        "502":
          description: The TCP target inside the sandbox refused the connection or was not listening
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
  /api/v1/ssh/enable:
    servers: *sandbox_proxy_http_servers
    post:
      tags:
        - sandbox-ssh
      summary: Enable SSH
      description: Enable the sandbox's internal SSH daemon for sandbox-proxy backend connections.
      operationId: sandbox_ssh_enable
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SandboxSshEnableRequest"
      responses:
        "200":
          description: SSH daemon status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxSshStatus"
        "401":
          description: Authenticated sandbox-proxy forwarding is required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
  /api/v1/ssh/disable:
    servers: *sandbox_proxy_http_servers
    post:
      tags:
        - sandbox-ssh
      summary: Disable SSH
      description: Stop the sandbox's internal SSH daemon.
      operationId: sandbox_ssh_disable
      responses:
        "200":
          description: SSH daemon status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxSshStatus"
        "401":
          description: Authenticated sandbox-proxy forwarding is required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
  /api/v1/ssh/status:
    servers: *sandbox_proxy_http_servers
    get:
      tags:
        - sandbox-ssh
      summary: SSH status
      description: Retrieve the sandbox's internal SSH daemon status.
      operationId: sandbox_ssh_status
      responses:
        "200":
          description: SSH daemon status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxSshStatus"
        "401":
          description: Authenticated sandbox-proxy forwarding is required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
  /api/v1/files:
    servers: *sandbox_proxy_http_servers
    parameters:
      - name: path
        in: query
        description: Absolute or relative file path inside the sandbox.
        required: true
        schema:
          type: string
    get:
      tags:
        - sandbox-files
      summary: Read a file
      description: Read a file through the sandbox proxy.
      operationId: sandbox_file_read
      responses:
        "200":
          description: File contents
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          description: Path points to a directory
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
        "403":
          description: Path traversal rejected
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
        "404":
          description: File not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
    put:
      tags:
        - sandbox-files
      summary: Write a file
      description: Write raw bytes to a sandbox file path through the sandbox proxy.
      operationId: sandbox_file_write
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        "204":
          description: File written successfully
        "403":
          description: Path traversal rejected
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
    delete:
      tags:
        - sandbox-files
      summary: Delete a file
      description: Delete a file through the sandbox proxy.
      operationId: sandbox_file_delete
      responses:
        "204":
          description: File deleted successfully
        "403":
          description: Path traversal rejected
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
        "404":
          description: File not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
  /api/v1/files/list:
    servers: *sandbox_proxy_http_servers
    parameters:
      - name: path
        in: query
        description: Absolute or relative directory path inside the sandbox.
        required: true
        schema:
          type: string
    get:
      tags:
        - sandbox-files
      summary: List a directory
      description: List directory contents through the sandbox proxy.
      operationId: sandbox_file_list
      responses:
        "200":
          description: Directory listing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxDirectoryListResponse"
        "400":
          description: Path is not a directory
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
        "403":
          description: Path traversal rejected
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
        "404":
          description: Directory not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxProxyError"
tags:
  - name: Tensorlake Cloud API
    description: Tensorlake Cloud APIs for Sandboxes, Document Ingestion, and Serverless Workflows
components:
  schemas:
    ApiError:
      type: object
      required:
        - message
        - code
        - timestamp
      properties:
        message:
          type: string
          description: A human-readable error message
        code:
          $ref: "#/components/schemas/ApiErrorCode"
          description: "The error code, which can be used to programmatically handle errors"
        timestamp:
          type: integer
          format: int64
          description: Millis since Unix epoch; easy to parse in every language
        trace_id:
          type:
            - string
            - "null"
          description: Optional request correlation-id for distributed tracing
        details:
          description: "Optional field-level validation errors, etc."
    ApiErrorCode:
      oneOf:
        - type: string
          enum:
            - QUOTA_EXCEEDED
        - type: string
          enum:
            - INVALID_JSON_SCHEMA
        - type: string
          enum:
            - INVALID_CONFIGURATION
        - type: string
          enum:
            - INVALID_PAGE_CLASSIFICATION
        - type: string
          enum:
            - ENTITY_NOT_FOUND
        - type: string
          enum:
            - ENTITY_ALREADY_EXISTS
        - type: string
          enum:
            - INVALID_FILE
        - type: string
          enum:
            - INVALID_PAGE_RANGE
        - type: string
          enum:
            - INVALID_MIME_TYPE
        - type: string
          enum:
            - INVALID_DATASET_NAME
        - type: string
          enum:
            - INVALID_JOB_STATE
        - type: string
          enum:
            - INTERNAL_ERROR
        - type: string
          enum:
            - INVALID_MULTIPART
        - type: string
          enum:
            - MULTIPART_STREAM_END
        - type: string
          enum:
            - CLIENT_DISCONNECT
        - type: string
          enum:
            - INVALID_ID
        - type: object
          required:
            - INVALID_QUERY_PARAMS
          properties:
            INVALID_QUERY_PARAMS:
              type: object
              required:
                - property
              properties:
                property:
                  type: string
                message:
                  type:
                    - string
                    - "null"
    Chunk:
      type: object
      required:
        - content
        - page_number
      properties:
        content:
          type: string
        page_number:
          type: integer
          minimum: 0
    ChunkingStrategy:
      type: string
      enum:
        - none
        - page
        - section
        - fragment
    ClassificationRequest:
      allOf:
        - $ref: "#/components/schemas/RequestFileInfo"
        - $ref: "#/components/schemas/ClassificationRequestConfiguration"
        - type: object
          properties:
            labels:
              type:
                - object
                - "null"
              description: "Additional metadata to identify the classification request. The labels\nare returned in the classification response."
              additionalProperties: {}
              propertyNames:
                type: string
              example:
                priority: high
                source: email
    ClassificationRequestConfiguration:
      type: object
      properties:
        page_classifications:
          type: array
          items:
            $ref: "#/components/schemas/PageClassConfig"
          description: "The properties of this object define the configuration for page\nclassify.\n\nIf this object is present, the API will perform page classify on\nthe document."
      additionalProperties: false
    Cursor:
      type: string
    Dataset:
      type: object
      required:
        - name
        - dataset_id
        - status
        - created_at
        - updated_at
      properties:
        name:
          type: string
          description: "The name of the dataset.\n\nThis is a human-readable name that identifies the dataset."
          example: Invoices Dataset
        dataset_id:
          type: string
          description: "The unique identifier for the dataset.\n\nThis identifier is used to refer to the dataset in API endpoints and\noperations.\n\nThis value is automatically generated and is unique within the\norganization and project context."
          example: dataset_12345
        description:
          type:
            - string
            - "null"
          description: "An optional description of the dataset.\n\nThis description is the one provided during dataset creation or update."
          example: This dataset contains invoices for the year 2023.
        status:
          $ref: "#/components/schemas/DatasetStatus"
          description: "The current status of the dataset.\n\nThis indicates whether the dataset is currently idle or processing."
        created_at:
          type: string
          description: "The date and time when the dataset was created.\n\nThe data is in RFC 3339 format (e.g., \"2023-10-01T12:00:00Z\")."
          example: "2023-10-01T12:00:00Z"
        updated_at:
          type: string
          description: "The date and time when the dataset was last updated.\n\nThe data is in RFC 3339 format (e.g., \"2023-10-01T12:00:00Z\")."
          example: "2023-10-01T12:00:00Z"
        analytics:
          oneOf:
            - type: "null"
            - $ref: "#/components/schemas/DatasetParseJobAnalytics"
              description: "Understand the status of the dataset and its parse jobs.\n\nThis field provides insights into the dataset's processing state,\nincluding the number of parse jobs in various states (processing,\npending, error, successful).\n\nTo retrieve detailed analytics, you can pass the `include_analytics`\nquery parameter\n\nThis is useful for monitoring and analytics purposes."
    DatasetCreateRequest:
      allOf:
        - $ref: "#/components/schemas/ParseConfiguration"
        - type: object
          required:
            - name
          properties:
            name:
              type: string
              description: "The name of the dataset.\n\nThe name can only contain alphanumeric characters, hyphens, and\nunderscores.\n\nThe name must be unique within the organization and project context."
              example: invoices dataset
            description:
              type:
                - string
                - "null"
              description: "A description of the dataset.\n\nThis field is optional and can be used to provide additional context\nabout the dataset."
              example: This dataset contains all invoices from 2023.
      description: "This object defines the request body for creating a new dataset.\n\nA Dataset is a collection of parsed results from files.\n\nIt can be used to store and manage related data, such as invoices, receipts,\nor any other documents that need to be parsed and analyzed.\n\nOnce a dataset is created, you can use it to parse related files using the\nsame configuration and options, allowing for consistent and efficient data\nextraction."
    DatasetCreatedResponse:
      type: object
      required:
        - name
        - dataset_id
        - created_at
      properties:
        name:
          type: string
          description: The human-readable name of the dataset provided during creation.
          example: invoices dataset
        dataset_id:
          type: string
          description: "The unique identifier for the dataset.\n\nThis identifier is used to refer to the dataset in API endpoints and\noperations.\n\nThis value is automatically generated and is unique within the\norganization and project context."
          example: dataset_12345
        created_at:
          type: string
          description: "The date and time when the dataset was created.\n\nThe date is in RFC 3339 format (e.g., \"2023-10-01T12:00:00Z\")."
          example: "2023-10-01T12:00:00Z"
    DatasetParseJobAnalytics:
      type: object
      required:
        - total_processing_parse_jobs
        - total_pending_parse_jobs
        - total_error_parse_jobs
        - total_successful_parse_jobs
        - total_jobs
      properties:
        total_processing_parse_jobs:
          type: integer
          format: int64
          description: "The total number of parse jobs that are on the `processing` state."
        total_pending_parse_jobs:
          type: integer
          format: int64
          description: "The total number of parse jobs that are on the `pending` state.\n\nPending parse jobs are those that have been created but not yet started\nprocessing."
        total_error_parse_jobs:
          type: integer
          format: int64
          description: "The total number of parse jobs that have encountered an error during\nprocessing.\n\nThese jobs have failed to complete successfully and require attention."
        total_successful_parse_jobs:
          type: integer
          format: int64
          description: "The total number of parse jobs that have been successfully processed.\n\nThese jobs have completed without errors and have produced results."
        total_jobs:
          type: integer
          format: int64
          description: The total number of parse jobs that have been created for the dataset.
    DatasetParseRequest:
      allOf:
        - $ref: "#/components/schemas/RequestFileInfo"
        - type: object
          properties:
            labels:
              type:
                - object
                - "null"
              description: "Additional metadata to identify the parse request. The labels are\nreturned in the parse response."
              additionalProperties: {}
              propertyNames:
                type: string
              example:
                priority: high
                source: email
    DatasetParsedResponse:
      type: object
      required:
        - parse_id
        - created_at
      properties:
        parse_id:
          type: string
          description: "The unique identifier for the parse job.\n\nUse this identifier to track the progress and results of the parse job\nusing the `/documents/v2/parse/{parse_id}` endpoint.\n\nThis identifier is used to track the parse job's progress and results."
          example: parse_id-12345
        created_at:
          type: string
          description: "The date and time when the parse job was scheduled.\n\nThe date is in RFC 3339 format (e.g., \"2023-10-01T12:00:00Z\")."
          example: "2023-10-01T12:00:00Z"
    DatasetStatus:
      type: string
      enum:
        - idle
        - processing
    DatasetUpdateRequest:
      allOf:
        - $ref: "#/components/schemas/ParseConfiguration"
        - type: object
          properties:
            description:
              type:
                - string
                - "null"
              description: "A description of the dataset.\n\nThis field is optional and can be used to provide additional context\nabout the dataset."
              example: This dataset contains all invoices from 2023.
    EditCreatedResponse:
      type: object
      required:
        - job_id
        - created_at
      properties:
        job_id:
          type: string
          description: "The unique identifier for the edit job"
        created_at:
          type: string
          description: "The creation date and time of the edit job.\n\nThe date is in RFC 3339 format."
    EditRequest:
      allOf:
        - $ref: "#/components/schemas/RequestFileInfo"
        - type: object
          properties:
            form_filling:
              $ref: "#/components/schemas/FormFillingOptions"
            labels:
              type:
                - object
                - "null"
              description: "Additional metadata to identify the edit request. The labels are\nreturned in the edit response."
              additionalProperties: {}
              propertyNames:
                type: string
              example:
                priority: high
                source: email
    EnrichmentOptions:
      type: object
      properties:
        table_cell_grounding:
          type: boolean
          description: "Grounding of table cells, providing the bounding box of the cells.\n\nThe default is `false`."
          default: false
        table_summarization:
          type: boolean
          description: "Generate a summary for parsed tables.\n\nThe default is `false`."
          default: false
        table_summarization_prompt:
          type:
            - string
            - "null"
          description: "The prompt to guide the table summarization.\nIgnored if `table_summarization` is `false`.\nDefault prompt - \"Summarize the table in a concise manner.\""
          default: ~
        figure_summarization:
          type: boolean
          description: "Generate a summary for parsed figures.\n\nThe default is `false`."
          default: false
        figure_summarization_prompt:
          type:
            - string
            - "null"
          description: "The prompt to guide the figure summarization.\nIgnored if `figure_summarization` is `false`.\nDefault prompt - \"Summarize the figure in a concise manner.\""
          default: ~
        chart_extraction:
          type: boolean
          description: "Extraction of chart type and structured data series from images, delivered as clean JSON suitable for analytics and ingestion.\n\nThe default is `false`."
          default: false
        key_value_extraction:
          type: boolean
          description: "Extraction of key/value pairs from forms as JSON.\n\nThe default is `false`."
          default: false
        include_full_page_image:
          type: boolean
          description: "Use full page image in addition to the cropped table and figure images.\nThis provides Language Models context about the table and figure they\nare summarizing in addition to the cropped images, and could improve the\nsummarization quality.\n\nThe default is `false`."
          default: false
      additionalProperties: false
    ExtractRequest:
      allOf:
        - $ref: "#/components/schemas/RequestFileInfo"
        - $ref: "#/components/schemas/ExtractionRequestConfiguration"
        - type: object
          properties:
            labels:
              type:
                - object
                - "null"
              description: "Additional metadata to identify the extraction request. The labels are\nreturned in the extraction response."
              additionalProperties: {}
              propertyNames:
                type: string
              example:
                priority: high
                source: email
    ExtractionRequestConfiguration:
      type: object
      properties:
        structured_extraction_options:
          type: array
          items:
            $ref: "#/components/schemas/StructuredExtractionOptions"
          description: "The properties of this object define the configuration for structured\ndata extraction.\n\nIf this object is present, the API will perform structured data\nextraction on the document."
      additionalProperties: false
    FileCreatedResponse:
      type: object
      required:
        - file_id
        - created_at
      properties:
        file_id:
          type: string
          description: "The ID of the created file\n\nUse this ID to reference the file in parse, datasets, and other\noperations."
          example: file_12345
        created_at:
          type: string
          description: "The creation date and time of the file.\n\nThis is in RFC 3339 format."
          example: "2023-10-01T12:00:00Z"
    FileMetadataResponse:
      type: object
      required:
        - file_id
        - mime_type
        - file_size
        - checksum_sha256
        - created_at
      properties:
        file_id:
          type: string
          description: "The ID of the file\n\nThis ID is used to reference the file in parse, datasets, and other\noperations."
          example: file_12345
        file_name:
          type:
            - string
            - "null"
          description: "The name of the file.\n\nThis is taken from the multipart form data or the file metadata.\n\nIt is not guaranteed to be unique, and it may not match the original\nfile name."
          example: example.pdf
        mime_type:
          $ref: "#/components/schemas/MimeType"
          description: "The content type of the file.\n\nThis is determined from the multipart form data, or from the\nfile extension."
        file_size:
          type: integer
          format: int64
          description: "The file size in bytes.\n\nThis is determined from the `Content-Length` header of the request,\nor from the file metadata.\n\nThis is not guaranteed to be accurate, as the file may be\ncompressed or encoded in a way that changes its size."
          example: 100000
          minimum: 0
        checksum_sha256:
          type: string
          description: "The SHA256 checksum of the file.\n\nThis is calculated from the file content and is used to verify the\nintegrity of the file."
          example: d3242c5c1d369d233fa65183bdd4c486eba109ceb13490ed291384eaffbe743b
        created_at:
          type: string
          description: "The creation date and time of the file.\n\nThis is in RFC 3339 format."
          example: "2023-10-01T12:00:00Z"
        labels:
          type: object
          description: "Labels submitted at the time of file upload.\n\nThis is a map of label names to their values."
          additionalProperties: {}
          propertyNames:
            type: string
          example: "{\"label1\": \"value1\", \"label2\": \"value2\"}"
    FormFillingOptions:
      type: object
      properties:
        fill_prompt:
          type:
            - string
            - "null"
          description: "A custom prompt to use for form filling."
        ignore_source_values:
          type: boolean
          description: "If true, the model will ignore existing values in the form fields and overwrite them."
          default: false
        no_acroform:
          type: boolean
          description: "If true, the model will not use AcroForm detection."
          default: false
        no_widget_detection:
          type: boolean
          description: "If true, the model will not do widget detection."
          default: false
      additionalProperties: false
    JobType:
      type: string
      enum:
        - parse
        - read
        - extract
        - classify
        - legacy
        - dataset
        - edit
    MimeType:
      type: string
      enum:
        - application/pdf
        - application/vnd.openxmlformats-officedocument.wordprocessingml.document
        - application/msword
        - application/vnd.openxmlformats-officedocument.presentationml.presentation
        - application/vnd.ms-powerpoint
        - application/vnd.apple.keynote
        - image/jpeg
        - image/tiff
        - text/plain
        - text/html
        - text/markdown
        - text/x-markdown
        - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
        - application/vnd.ms-excel.sheet.macroenabled.12
        - application/vnd.ms-excel
        - text/xml
        - text/csv
        - image/png
        - text/rtf
        - application/rtf
        - application/octet-stream
        - application/pkcs7-mime
        - application/x-pkcs7-mime
        - application/pkcs7-signature
    Model:
      type: string
      enum:
        - tensorlake
        - gemini3
        - sonnet
        - gpt4o_mini
    OcrPipelineProvider:
      type: string
      enum:
        - model01
        - model02
        - model03
        - gemini3
        - model06
    OneOrMany_usize:
      oneOf:
        - type: integer
          minimum: 0
        - type: array
          items:
            type: integer
            minimum: 0
      description: Common objects used across multiple endpoints in the API.
    Page:
      type: object
      description: "Entity representing a single page in the parsed document.\n\nEach page contains a list of fragments, which are detected objects such as\ntables, text, figures, section headers, etc."
      required:
        - page_number
      properties:
        page_number:
          type: integer
          description: 1-indexed page number in the document.
          minimum: 0
        page_fragments:
          type:
            - array
            - "null"
          items:
            $ref: "#/components/schemas/PageFragment"
          description: "Vector of text fragments extracted from the page.\n\nEach fragment represents a distinct section of text, such as titles,\nparagraphs, tables, figures, etc."
        dimensions:
          type:
            - array
            - "null"
          items:
            type: integer
            format: int32
          description: "Dimensions is a 2-element vector representing the width and height of\nthe page in points."
        page_dimensions:
          oneOf:
            - type: "null"
            - $ref: "#/components/schemas/PageDimensions"
              description: "Dimensions of the page.\n\nThis is only populated if the page dimensions could be determined."
        classification_reason:
          type:
            - string
            - "null"
          description: "If the page was classified into a specific class, this field contains\nthe reason for the classification."
    PageClass:
      type: object
      description: "The classification result for a parse request that included\n`page_classification_options`."
      required:
        - page_class
        - page_numbers
      properties:
        page_class:
          type: string
          description: "The name of the page class given in the parse request.\n\nThis value should match one of the class names provided in the\n`page_classification_options` field of the parse request."
        page_numbers:
          type: array
          items:
            type: integer
            format: int32
          description: A list of page numbers (1-indexed) where the page class was detected.
        classification_reasons:
          type:
            - object
            - "null"
          description: "A map of reasons for classifying each page into this class.\n\nThe keys are the page numbers (1-indexed) and the values are the reasons\nfor classifying that page into this class.\n\nThis field is optional and may be omitted if no reasons were provided\nduring classification."
          additionalProperties:
            type: string
          propertyNames:
            type: integer
            format: int32
    PageClassConfig:
      type: object
      required:
        - name
        - description
      properties:
        name:
          type: string
          description: The name of the page class.
        description:
          type: string
          description: "The description of the page class to guide the model to classify the\npages. Describe what the model should look for in the page to\nclassify it."
    PageDimensions:
      type: object
      required:
        - width
        - height
      properties:
        width:
          type: integer
          format: int32
          description: Width of the page in points.
        height:
          type: integer
          format: int32
          description: Height of the page in points.
    PageFragment:
      type: object
      required:
        - fragment_type
        - content
      properties:
        fragment_type:
          $ref: "#/components/schemas/PageFragmentType"
        content: {}
        reading_order:
          type:
            - integer
            - "null"
          format: int64
        bbox:
          type:
            - object
            - "null"
          additionalProperties:
            type: number
            format: double
          propertyNames:
            type: string
    PageFragmentType:
      type: string
      enum:
        - section_header
        - title
        - text
        - table
        - figure
        - chart
        - formula
        - form
        - key_value_region
        - document_index
        - list_item
        - table_caption
        - figure_caption
        - formula_caption
        - page_footer
        - page_header
        - page_number
        - signature
        - strikethrough
        - tracked_changes
        - comments
        - barcode
    PageRange:
      oneOf:
        - type: array
          items:
            type: integer
            format: int32
            minimum: 0
          uniqueItems: true
        - type: string
    PaginationDirection:
      type: string
      enum:
      - next
      - prev
    ContainerResourcesInfo:
      type: object
      required:
        - cpus
        - memory_mb
        - disk_mb
      properties:
        cpus:
          type: number
          format: double
          description: CPU allocation in cores.
        memory_mb:
          type: integer
          format: int64
          description: Memory allocation in MiB.
        disk_mb:
          type: integer
          format: int64
          description: Ephemeral root filesystem size in MiB.
    GPUResources:
      type: object
      required:
        - count
        - model
      properties:
        count:
          type: integer
          format: int32
          minimum: 1
        model:
          type: string
    SandboxCursorDirection:
      type: string
      enum:
        - forward
        - backward
    SandboxListStatusFilter:
      type: string
      enum:
        - running
        - suspended
    SandboxStatus:
      type: string
      enum:
        - pending
        - running
        - snapshotting
        - suspending
        - suspended
        - terminated
    SandboxPendingReason:
      type: string
      enum:
        - scheduling
        - waiting_for_container
        - no_executors_available
        - no_resources_available
        - pool_at_capacity
    SandboxNetworkAccessControl:
      type: object
      properties:
        allow_internet_access:
          type: boolean
          default: true
          description: Allows internet access, including DNS requests. If false, all outbound traffic except destinations in allow_out is blocked, including DNS requests. If allow_out is non-empty and this is true, only the listed destinations and DNS requests are allowed.
        allow_out:
          type: array
          description: Allowed domains, IPv4 addresses, or IPv4 CIDRs. A non-empty list allows the listed destinations and DNS requests when allow_internet_access is true. Hostname rules are followed across DNS changes. A destination also matched by deny_out is blocked.
          items:
            type: string
        deny_out:
          type: array
          description: Denied domains, IPv4 addresses, or IPv4 CIDRs. Takes precedence over allow_out; a destination matched by both is blocked.
          items:
            type: string
    SandboxResourceOverrides:
      type: object
      properties:
        cpus:
          type: number
          format: double
          description: CPU allocation override in cores.
        memory_mb:
          type: integer
          format: int64
          description: Memory allocation override in MiB.
        disk_mb:
          type: integer
          format: int64
          minimum: 10240
          maximum: 102400
          description: |
            Ephemeral root filesystem size in MiB. Defaults to 10240 (10 GiB).
            Must be between 10240 and 102400 inclusive. For filesystem snapshots,
            this can be used with snapshot_id to grow root disk size (growth-only).
        gpus:
          type: array
          items:
            $ref: "#/components/schemas/GPUResources"
          description: Optional GPU allocation override.
    FileSystemMount:
      type: object
      required:
        - file_system_id
        - mount_path
      properties:
        file_system_id:
          type: string
          description: Filesystem name within the project — the name created with `tl fs create <name>`. ASCII letters, digits, `_`, and `-` only.
        mount_path:
          type: string
          description: Absolute guest mount path (e.g. `/mnt/skills`). Must not be `/` or contain `..`; paths are normalized, and mount paths must be unique and non-nested within the sandbox.
        read_only:
          type: boolean
          default: false
          description: Mount the filesystem read-only. Writes inside the guest fail with `EROFS`; the mount's storage credential carries no write scope. Fail-closed — sandboxes requesting read-only mounts are only placed on fleets that can enforce them.
        prefetch:
          type: boolean
          default: false
          description: Download the filesystem's full tree in the background after the mount is ready. The mount is usable immediately with lazy reads meanwhile. Best-effort — never blocks or fails the sandbox, and older fleets skip it silently.
        snapshot_id:
          type: string
          description: Pin the mount to a permanent snapshot of the filesystem (created with `tl fs snapshot` or a message-bearing `tl fs push`; ids listed by `tl fs history`). A pinned mount serves exactly that snapshot and never follows the live filesystem head. Requires `read_only` to be `true` — a `snapshot_id` without `read_only` is rejected with `400`. Pinning an id that is not a permanent snapshot of the filesystem fails the sandbox with `termination_reason` `FileSystemSnapshotNotFound`. Omit for an unpinned mount that follows the live filesystem; responses omit the field for unpinned mounts.
    DetachFileSystemRequest:
      type: object
      required:
        - mount_path
      properties:
        mount_path:
          type: string
          description: Absolute guest mount path of the filesystem to detach.
    CreateSandboxRequest:
      type: object
      properties:
        image:
          type: string
          description: Optional sandbox image name to boot from. When omitted, Tensorlake uses the default managed environment. This can also be a registered Sandbox Image name.
        resources:
          $ref: "#/components/schemas/SandboxResourceOverrides"
        secret_names:
          type: array
          description: Secret names to inject into the sandbox.
          items:
            type: string
        timeout_secs:
          type: integer
          format: int64
          minimum: 0
          description: |
            Sandbox timeout in seconds. `0` requests the maximum allowed by your plan.
            Plan maximums: Free unverified 3600 (1h), Free verified 7200 (2h),
            On-Demand 86400 (24h). See [tensorlake.ai/pricing](https://www.tensorlake.ai/pricing) for higher limits on committed plans.
        entrypoint:
          type: array
          description: Optional command to run when the sandbox starts.
          items:
            type: string
        network:
          $ref: "#/components/schemas/SandboxNetworkAccessControl"
        snapshot_id:
          type: string
          description: Snapshot to restore from.
        allow_unauthenticated_access:
          type: boolean
          description: Allow sandbox ingress to route requests without validating auth credentials. The legacy request alias `allow_unauthenticated_proxy_access` is also accepted.
        exposed_ports:
          type: array
          description: Additional sandbox ports that public ingress may route to. When omitted, only the management port `9501` is routable.
          items:
            type: integer
            format: int32
            minimum: 1
            maximum: 65535
        template_id:
          type: string
          description: Template identifier to associate with the launched sandbox.
        name:
          type: string
          description: Optional user-provided sandbox name. When set, the sandbox is named and supports suspend/resume. When omitted, the sandbox is ephemeral.
        file_systems:
          type: array
          description: Filesystems to mount into the sandbox, each at its own absolute, unique, non-nested guest mount path. At most 8 per sandbox. Mounts are ready before the sandbox is reported as running; a filesystem that does not exist fails the create with `422` and reason `FileSystemNotFound`, and a pinned `snapshot_id` that is not a permanent snapshot fails it with reason `FileSystemSnapshotNotFound`.
          items:
            $ref: "#/components/schemas/FileSystemMount"
    CreateSandboxResponse:
      type: object
      required:
        - sandbox_id
        - status
      properties:
        sandbox_id:
          type: string
        status:
          $ref: "#/components/schemas/SandboxStatus"
        pending_reason:
          $ref: "#/components/schemas/SandboxPendingReason"
        ingress_endpoint:
          type:
            - string
            - "null"
          description: Base ingress origin for this sandbox's current placement.
    CopySandboxResponse:
      type: object
      required:
        - source_sandbox_id
        - sandboxes
      properties:
        source_sandbox_id:
          type: string
          description: The sandbox the copies were made from.
        sandboxes:
          type: array
          description: >-
            One entry per requested copy, in creation order. On a 422 or 504 the
            entries report per-copy status, so inspect each one to see which
            copies became ready.
          items:
            $ref: "#/components/schemas/CreateSandboxResponse"
    SandboxInfo:
      type: object
      required:
        - id
        - namespace
        - status
        - created_at
        - resources
        - timeout_secs
        - allow_unauthenticated_access
      properties:
        id:
          type: string
        namespace:
          type: string
        image:
          type: string
        status:
          $ref: "#/components/schemas/SandboxStatus"
        pending_reason:
          type:
            - string
            - "null"
          description: Present when `status` is `pending`.
        outcome:
          type:
            - string
            - "null"
          description: Platform-specific termination outcome string returned for completed sandboxes.
        termination_reason:
          type:
            - string
            - "null"
          description: Typed reason the sandbox terminated (e.g. `FileSystemNotFound`, `FileSystemSnapshotNotFound`, `ImageNotFound`). Present on failed terminations.
        error_details:
          type:
            - string
            - "null"
          description: Human-readable detail accompanying `termination_reason`.
        created_at:
          type: integer
          format: int64
          description: Milliseconds since Unix epoch.
        container_id:
          type:
            - string
            - "null"
        executor_id:
          type:
            - string
            - "null"
        resources:
          $ref: "#/components/schemas/ContainerResourcesInfo"
        timeout_secs:
          type: integer
          format: int64
        ingress_endpoint:
          type:
            - string
            - "null"
          description: Canonical server-provided base for sandbox-specific ingress.
        sandbox_url:
          type:
            - string
            - "null"
          description: Sandbox-specific management URL derived from `ingress_endpoint`.
        pool_id:
          type:
            - string
            - "null"
        network_policy:
          oneOf:
            - type: "null"
            - $ref: "#/components/schemas/SandboxNetworkAccessControl"
        allow_unauthenticated_access:
          type: boolean
          description: Whether sandbox ingress may route requests without auth validation.
        exposed_ports:
          type:
            - array
            - "null"
          items:
            type: integer
            format: int32
            minimum: 1
            maximum: 65535
          description: Additional routable ingress ports. When `null`, only the management port `9501` is routable.
        template_id:
          type:
            - string
            - "null"
        name:
          type:
            - string
            - "null"
        file_systems:
          type: array
          description: Filesystems currently mounted into the sandbox.
          items:
            $ref: "#/components/schemas/FileSystemMount"
    ListSandboxesResponse:
      type: object
      required:
        - sandboxes
      properties:
        sandboxes:
          type: array
          items:
            $ref: "#/components/schemas/SandboxInfo"
        prev_cursor:
          type:
            - string
            - "null"
        next_cursor:
          type:
            - string
            - "null"
    PatchSandboxRequest:
      type: object
      properties:
        allow_unauthenticated_access:
          type: boolean
          description: Set or clear unauthenticated ingress routing for this sandbox.
        exposed_ports:
          type: array
          description: Replace the exposed port allowlist. Pass an empty array to clear it and revert to the default management port only.
          items:
            type: integer
            format: int32
            minimum: 1
            maximum: 65535
        network:
          allOf:
            - $ref: "#/components/schemas/SandboxNetworkAccessControl"
          description: >-
            Update the egress network policy of the running sandbox. This field
            is tri-state: omit it to leave the current policy unchanged, send an
            object to replace the whole policy, or send an explicit null to
            clear it (unrestricted egress). The change is applied to the live
            sandbox firewall as one atomic swap with no enforcement gap;
            already-established connections are not revoked. If a hostname in
            the new policy fails to resolve, the update is rejected and the
            previous policy stays enforced.
    PaginatedResult_Dataset:
      type: object
      required:
        - items
        - has_more
      properties:
        items:
          type: array
          items:
            type: object
            required:
              - name
              - dataset_id
              - status
              - created_at
              - updated_at
            properties:
              name:
                type: string
                description: "The name of the dataset.\n\nThis is a human-readable name that identifies the dataset."
                example: Invoices Dataset
              dataset_id:
                type: string
                description: "The unique identifier for the dataset.\n\nThis identifier is used to refer to the dataset in API endpoints and\noperations.\n\nThis value is automatically generated and is unique within the\norganization and project context."
                example: dataset_12345
              description:
                type:
                  - string
                  - "null"
                description: "An optional description of the dataset.\n\nThis description is the one provided during dataset creation or update."
                example: This dataset contains invoices for the year 2023.
              status:
                $ref: "#/components/schemas/DatasetStatus"
                description: "The current status of the dataset.\n\nThis indicates whether the dataset is currently idle or processing."
              created_at:
                type: string
                description: "The date and time when the dataset was created.\n\nThe data is in RFC 3339 format (e.g., \"2023-10-01T12:00:00Z\")."
                example: "2023-10-01T12:00:00Z"
              updated_at:
                type: string
                description: "The date and time when the dataset was last updated.\n\nThe data is in RFC 3339 format (e.g., \"2023-10-01T12:00:00Z\")."
                example: "2023-10-01T12:00:00Z"
              analytics:
                oneOf:
                  - type: "null"
                  - $ref: "#/components/schemas/DatasetParseJobAnalytics"
                    description: "Understand the status of the dataset and its parse jobs.\n\nThis field provides insights into the dataset's processing state,\nincluding the number of parse jobs in various states (processing,\npending, error, successful).\n\nTo retrieve detailed analytics, you can pass the `include_analytics`\nquery parameter\n\nThis is useful for monitoring and analytics purposes."
        has_more:
          type: boolean
        next_cursor:
          type:
            - string
            - "null"
        prev_cursor:
          type:
            - string
            - "null"
    PaginatedResult_FileMetadataResponse:
      type: object
      required:
        - items
        - has_more
      properties:
        items:
          type: array
          items:
            type: object
            required:
              - file_id
              - mime_type
              - file_size
              - checksum_sha256
              - created_at
            properties:
              file_id:
                type: string
                description: "The ID of the file\n\nThis ID is used to reference the file in parse, datasets, and other\noperations."
                example: file_12345
              file_name:
                type:
                  - string
                  - "null"
                description: "The name of the file.\n\nThis is taken from the multipart form data or the file metadata.\n\nIt is not guaranteed to be unique, and it may not match the original\nfile name."
                example: example.pdf
              mime_type:
                $ref: "#/components/schemas/MimeType"
                description: "The content type of the file.\n\nThis is determined from the multipart form data, or from the\nfile extension."
              file_size:
                type: integer
                format: int64
                description: "The file size in bytes.\n\nThis is determined from the `Content-Length` header of the request,\nor from the file metadata.\n\nThis is not guaranteed to be accurate, as the file may be\ncompressed or encoded in a way that changes its size."
                example: 100000
                minimum: 0
              checksum_sha256:
                type: string
                description: "The SHA256 checksum of the file.\n\nThis is calculated from the file content and is used to verify the\nintegrity of the file."
                example: d3242c5c1d369d233fa65183bdd4c486eba109ceb13490ed291384eaffbe743b
              created_at:
                type: string
                description: "The creation date and time of the file.\n\nThis is in RFC 3339 format."
                example: "2023-10-01T12:00:00Z"
              labels:
                type: object
                description: "Labels submitted at the time of file upload.\n\nThis is a map of label names to their values."
                additionalProperties: {}
                propertyNames:
                  type: string
                example: "{\"label1\": \"value1\", \"label2\": \"value2\"}"
        has_more:
          type: boolean
        next_cursor:
          type:
            - string
            - "null"
        prev_cursor:
          type:
            - string
            - "null"
    PaginatedResult_ParseResult:
      type: object
      required:
        - items
        - has_more
      properties:
        items:
          type: array
          items:
            type: object
            required:
              - parse_id
              - status
              - created_at
            properties:
              parse_id:
                type: string
                description: "The unique identifier for the parse job\n\nThis is the same as the value returned from the `POST\n/documents/v2/parse` endpoint."
                default: ""
                example: parse_abcd1234
              dataset_id:
                type:
                  - string
                  - "null"
                description: "If the parse job was scheduled from a dataset, this field contains the\ndataset id.\n\nThis is the identifier used in URLs and API endpoints to refer to the\ndataset."
                default: ~
              parsed_pages_count:
                type: integer
                description: "The number of pages that were parsed successfully.\n\nThis is the total number of pages that were successfully parsed in the\ndocument."
                default: 0
                example: 5
                minimum: 0
              total_pages:
                type:
                  - integer
                  - "null"
                description: "The total number of pages in the document.\n\nThis is the total number of pages in the original document that was\nparsed.\n\nThis value is only populated once the parse job is completed\nsuccessfully."
                default: ~
                minimum: 0
              status:
                oneOf:
                  - $ref: "#/components/schemas/ParseStatus"
                    description: "The status of the parse job.\n\nThis indicates whether the job is pending, in progress, completed, or\nfailed.\n\nThis can be used to track the progress of the parse operation."
                default: pending
              error:
                type:
                  - string
                  - "null"
                description: "Error occurred during any part of the parse execution.\n\nThis is only populated if the parse operation failed."
                default: ~
              pages:
                type:
                  - array
                  - "null"
                items:
                  $ref: "#/components/schemas/Page"
                description: "List of pages parsed from the document.\n\nEach page has a list of fragments, which are detected objects such as\ntables, text, figures, section headers, etc.\n\nWe also return the detected text, structure of the table(if its a\ntable), and the bounding box of the object."
                default: ~
              chunks:
                type: array
                items:
                  $ref: "#/components/schemas/Chunk"
                description: "Chunks of the document.\n\nThis is a vector of `Chunk` objects, each containing a chunk of the\ndocument.\nThe number of chunks depend on the chunking strategy used during\nparsing."
                default: []
              structured_data:
                type:
                  - array
                  - "null"
                items:
                  $ref: "#/components/schemas/StructuredData"
                description: "Structured data extracted from the document.\n\nThe structured data is a map where the keys are the schema names\nprovided in the parse request, and the values are\n`StructuredData` objects containing the structured data extracted from\nthe document.\n\nThe number of structured data objects depends on the partition strategy\n**None** - one structured data object for the entire document.\n**Page** - one structured data object for each page."
                default: ~
              page_classes:
                type:
                  - array
                  - "null"
                items:
                  $ref: "#/components/schemas/PageClass"
                description: "Page classes extracted from the document.\n\nThis is a map where the keys are page class names provided in the parse\nrequest under the `page_classification_options` field,\nand the values are vectors of page numbers (1-indexed) where each page\nclass appears.\n\nThis is used to categorize pages in the document based on the\nclassify options provided."
                default: ~
              pdf_base64:
                type:
                  - string
                  - "null"
                description: "The raw content of generated PDF, encoded in base64.\n\nAt the moment, this is only populated for DOCX files.\nThe PDF is generated from the original DOCX file."
                default: ~
              tasks_completed_count:
                type:
                  - integer
                  - "null"
                description: "The number of tasks that have been completed for the parse job.\n\nThis is the number of tasks that have been successfully processed in the\nparse job.\n\nIt can be used to track the progress of the parse operation."
                default: ~
                minimum: 0
              tasks_total_count:
                type:
                  - integer
                  - "null"
                description: "The total number of tasks that are expected to be completed for the\nparse job.\n\nThis is the total number of tasks that are expected to be processed in\nthe parse job."
                default: ~
                minimum: 0
              created_at:
                type: string
                description: "The date and time when the parse job was created.\n\nThe date is in RFC 3339 format.\n\nThis can be used to track when the parse job was initiated."
                default: ""
                example: "2023-10-01T12:00:00Z"
              finished_at:
                type:
                  - string
                  - "null"
                description: "The date and time when the parse job was finished.\n\nThe date is in RFC 3339 format.\n\nThis can be undefined if the parse job is still in progress or pending."
                default: ~
              labels:
                type: object
                description: "Labels associated with the parse job.\n\nThese are the key-value, or json, pairs submitted with the parse\nrequest.\n\nThis can be used to categorize or tag the parse job for easier\nidentification and filtering.\n\nIt can be undefined if no labels were provided in the request."
                default: {}
                additionalProperties: {}
                propertyNames:
                  type: string
              options:
                oneOf:
                  - type: "null"
                  - $ref: "#/components/schemas/ParseRequestOptions"
                default: ~
              usage:
                oneOf:
                  - type: "null"
                  - $ref: "#/components/schemas/Usage"
                    description: "Resource usage associated with the parse job.\n\nThis includes details such as number of pages parsed, tokens used for\nOCR and extraction, etc.\n\nUsage is only populated for successful jobs.\n\nBilling is based on the resource usage."
                default: ~
              message_update:
                type:
                  - string
                  - "null"
                description: "Message update associated with the parse job.\n\nThis is used to provide progress update information about the parse job."
                default: ~
        has_more:
          type: boolean
        next_cursor:
          type:
            - string
            - "null"
        prev_cursor:
          type:
            - string
            - "null"
    ParseConfiguration:
      type: object
      properties:
        parsing_options:
          $ref: "#/components/schemas/ParsingOptions"
          description: "The properties of this object define the configuration for the document\nparsing process.\n\nTensorlake provides sane defaults that work well for most\ndocuments, so this object is not required. However, every document\nis different, and you may want to customize the parsing process to\nbetter suit your needs."
        structured_extraction_options:
          type:
            - array
            - "null"
          items:
            $ref: "#/components/schemas/StructuredExtractionOptions"
          description: "The properties of this object define the configuration for structured\ndata extraction.\n\nIf this object is present, the API will perform structured data\nextraction on the document."
        page_classifications:
          type:
            - array
            - "null"
          items:
            $ref: "#/components/schemas/PageClassConfig"
          description: "The properties of this object define the configuration for page\nclassify.\n\nIf this object is present, the API will perform page classify on\nthe document."
        enrichment_options:
          $ref: "#/components/schemas/EnrichmentOptions"
          description: "The properties of this object help to extend the output of the document\nparsing process with additional information.\n\nThis includes summarization of tables and figures, which can help to\nprovide a more comprehensive understanding of the document.\n\nThis object is not required, and the API will use default settings if it\nis not present."
    ParseCreatedResponse:
      type: object
      required:
        - parse_id
        - created_at
      properties:
        parse_id:
          type: string
          description: "The unique identifier for the parse job\n\nThis is the ID that can be used to track the status of the parse job.\nUsed in the `GET /documents/v2/parse/{parse_id}` endpoint to retrieve\nthe status and results of the parse job."
        created_at:
          type: string
          description: "The creation date and time of the parse job.\n\nThe date is in RFC 3339 format."
    ParseRequest:
      allOf:
        - $ref: "#/components/schemas/RequestFileInfo"
        - $ref: "#/components/schemas/ParseConfiguration"
        - type: object
          properties:
            labels:
              type:
                - object
                - "null"
              description: "Additional metadata to identify the parse request. The labels are\nreturned in the parse response."
              additionalProperties: {}
              propertyNames:
                type: string
              example:
                priority: high
                source: email
    ParseRequestOptions:
      type: object
      required:
        - job_type
        - configuration
      properties:
        file_id:
          type:
            - string
            - "null"
          description: "The tensorlake file ID.\n\nThis is the ID of the file used for the parse job. It has `tensorlake_`\nprefix.\n\nIt can be undefined if the parse operation was created with a `file_url`\nor `raw_text` field instead of a file ID."
        file_url:
          type:
            - string
            - "null"
          description: "The URL of the file used for the parse job.\n\nIt can be undefined if the parse operation was created with a `file_id`\nor `raw_text` field instead of a file URL."
        raw_text:
          type:
            - string
            - "null"
          description: "The raw_text for the parse job.\n\nThis is only populated if the parse operation was created with a\n`raw_text` field. And the mime type is of a text-based format (e.g.,\nplain text, HTML).\n\nIt can be undefined if the parse operation was created with a `file_id`\nor `file_url` field instead of raw_text."
        file_name:
          type:
            - string
            - "null"
          description: "The name of the file used for the parse job.\n\nThis is only populated if the parse operation was created with a\n`file_id`."
        file_labels:
          type: object
          description: "Labels associated to the file used for the parse job.\n\nThese are the key-value, or json, pairs submitted with the file\nupload."
          additionalProperties: {}
          propertyNames:
            type: string
        mime_type:
          oneOf:
            - type: "null"
            - $ref: "#/components/schemas/MimeType"
              description: "The mime type of the file used for the parse job.\n\nThis can be undefined if the file has been removed since the parse job\nwas created, or if the parse operation was created with a `file_url`\nfield instead of a `file_id` or `raw_text`."
        trace_id:
          type:
            - string
            - "null"
          description: "The trace ID for the parse job.\n\nIt can be undefined if the operation is still in pending state.\n\nThis is used for debugging purposes."
        page_range:
          oneOf:
            - type: "null"
            - $ref: "#/components/schemas/PageRange"
              description: "The page range that was requested for parsing.\n\nThis is the same as the value provided in the `pages` field of the\nrequest.\n\nIt can be undefined if the parse operation was created without a\nspecific page range. Meaning the whole document was parsed."
        job_type:
          $ref: "#/components/schemas/JobType"
          description: "The type of job that was created.\n\nThis indicates whether the job was created via the Parse, Read, Extract,\nClassification, Legacy, or Dataset endpoint."
        configuration:
          $ref: "#/components/schemas/ParseConfiguration"
          description: "The configuration used for the parse job.\n\nThis is derived from the configuration settings submitted with the parse\nrequest.\n\nIt can be used to understand how the parse job was configured, such as\nthe parsing strategy, extraction methods, etc.\n\nValues not provided in the request will be set to their default values."
    ParseResult:
      type: object
      required:
        - parse_id
        - status
        - created_at
      properties:
        parse_id:
          type: string
          description: "The unique identifier for the parse job\n\nThis is the same as the value returned from the `POST\n/documents/v2/parse` endpoint."
          default: ""
          example: parse_abcd1234
        dataset_id:
          type:
            - string
            - "null"
          description: "If the parse job was scheduled from a dataset, this field contains the\ndataset id.\n\nThis is the identifier used in URLs and API endpoints to refer to the\ndataset."
          default: ~
        parsed_pages_count:
          type: integer
          description: "The number of pages that were parsed successfully.\n\nThis is the total number of pages that were successfully parsed in the\ndocument."
          default: 0
          example: 5
          minimum: 0
        total_pages:
          type:
            - integer
            - "null"
          description: "The total number of pages in the document.\n\nThis is the total number of pages in the original document that was\nparsed.\n\nThis value is only populated once the parse job is completed\nsuccessfully."
          default: ~
          minimum: 0
        status:
          oneOf:
            - $ref: "#/components/schemas/ParseStatus"
              description: "The status of the parse job.\n\nThis indicates whether the job is pending, in progress, completed, or\nfailed.\n\nThis can be used to track the progress of the parse operation."
          default: pending
        error:
          type:
            - string
            - "null"
          description: "Error occurred during any part of the parse execution.\n\nThis is only populated if the parse operation failed."
          default: ~
        pages:
          type:
            - array
            - "null"
          items:
            $ref: "#/components/schemas/Page"
          description: "List of pages parsed from the document.\n\nEach page has a list of fragments, which are detected objects such as\ntables, text, figures, section headers, etc.\n\nWe also return the detected text, structure of the table(if its a\ntable), and the bounding box of the object."
          default: ~
        chunks:
          type: array
          items:
            $ref: "#/components/schemas/Chunk"
          description: "Chunks of the document.\n\nThis is a vector of `Chunk` objects, each containing a chunk of the\ndocument.\nThe number of chunks depend on the chunking strategy used during\nparsing."
          default: []
        structured_data:
          type:
            - array
            - "null"
          items:
            $ref: "#/components/schemas/StructuredData"
          description: "Structured data extracted from the document.\n\nThe structured data is a map where the keys are the schema names\nprovided in the parse request, and the values are\n`StructuredData` objects containing the structured data extracted from\nthe document.\n\nThe number of structured data objects depends on the partition strategy\n**None** - one structured data object for the entire document.\n**Page** - one structured data object for each page."
          default: ~
        page_classes:
          type:
            - array
            - "null"
          items:
            $ref: "#/components/schemas/PageClass"
          description: "Page classes extracted from the document.\n\nThis is a map where the keys are page class names provided in the parse\nrequest under the `page_classification_options` field,\nand the values are vectors of page numbers (1-indexed) where each page\nclass appears.\n\nThis is used to categorize pages in the document based on the\nclassify options provided."
          default: ~
        pdf_base64:
          type:
            - string
            - "null"
          description: "The raw content of generated PDF, encoded in base64.\n\nAt the moment, this is only populated for DOCX files.\nThe PDF is generated from the original DOCX file."
          default: ~
        merged_tables:
          type: array
          items:
            $ref: "#/components/schemas/MergedTable"
          description: "Merged tables extracted from the document.\n\nThis is a list of `MergedTable` objects containing the merged tables extracted from the document. Tables are merged if they are part of the same logical table."
          default: []
        tasks_completed_count:
          type:
            - integer
            - "null"
          description: "The number of tasks that have been completed for the parse job.\n\nThis is the number of tasks that have been successfully processed in the\nparse job.\n\nIt can be used to track the progress of the parse operation."
          default: ~
          minimum: 0
        tasks_total_count:
          type:
            - integer
            - "null"
          description: "The total number of tasks that are expected to be completed for the\nparse job.\n\nThis is the total number of tasks that are expected to be processed in\nthe parse job."
          default: ~
          minimum: 0
        created_at:
          type: string
          description: "The date and time when the parse job was created.\n\nThe date is in RFC 3339 format.\n\nThis can be used to track when the parse job was initiated."
          default: ""
          example: "2023-10-01T12:00:00Z"
        finished_at:
          type:
            - string
            - "null"
          description: "The date and time when the parse job was finished.\n\nThe date is in RFC 3339 format.\n\nThis can be undefined if the parse job is still in progress or pending."
          default: ~
        labels:
          type: object
          description: "Labels associated with the parse job.\n\nThese are the key-value, or json, pairs submitted with the parse\nrequest.\n\nThis can be used to categorize or tag the parse job for easier\nidentification and filtering.\n\nIt can be undefined if no labels were provided in the request."
          default: {}
          additionalProperties: {}
          propertyNames:
            type: string
        options:
          oneOf:
            - type: "null"
            - $ref: "#/components/schemas/ParseRequestOptions"
          default: ~
        usage:
          oneOf:
            - type: "null"
            - $ref: "#/components/schemas/Usage"
              description: "Resource usage associated with the parse job.\n\nThis includes details such as number of pages parsed, tokens used for\nOCR and extraction, etc.\n\nUsage is only populated for successful jobs.\n\nBilling is based on the resource usage."
          default: ~
        message_update:
          type:
            - string
            - "null"
          description: "Message update associated with the parse job.\n\nThis is used to provide progress update information about the parse job."
          default: ~
    ParseStatus:
      type: string
      enum:
        - pending
        - processing
        - detecting_layout
        - detected_layout
        - extracting_data
        - extracted_data
        - formatting_output
        - formatted_output
        - successful
        - failure
    ParsingOptions:
      type: object
      properties:
        table_output_mode:
          oneOf:
            - $ref: "#/components/schemas/TableOutputMode"
              description: "The format for the tables extracted from the document.\n\n`HTML` - tables are represented as HTML strings.\n`Markdown` - tables are represented as Markdown strings.\n\nThe default is `HTML`."
          default: html
        table_parsing_format:
          oneOf:
            - $ref: "#/components/schemas/TableParsingFormat"
              description: "Determines which model the system uses to identify and extract tables\nfrom the document.\n\n`tsr` - identifies the structure of\nthe table first, and then the cells of the tables. Better suited for\ndense, long or grid-like tables.\n`vlm` - uses a VLM model to identify and extract the cells of the\ntables. Better suited for tables with merged cells or irregular\nstructures.\n\nThe default is `tsr`."
          default: tsr
        chunking_strategy:
          oneOf:
            - $ref: "#/components/schemas/ChunkingStrategy"
              description: "Determines how the document is chunked into smaller pieces.\n\n`None` - no chunking is applied.\n`Page` - chunks the document into pages.\n`Section` - chunks the document into sections.\n`Fragment` - chunks the document by objects detected in the document.\nEvery text block, image, table, etc. is considered a fragment.\n\nThe default is `None`."
          default: none
        signature_detection:
          type: boolean
          description: "Flag to enable the detection of signatures in the document.\n\nThis flag incurs additional billing costs.\n\nThe default is `false`."
          default: false
        remove_strikethrough_lines:
          type: boolean
          description: "Flag to enable the detection, and removal, of strikethrough text in the\ndocument.\n\nThis flag incurs additional billing costs.\n\nThe default is `false`."
          default: false
        skew_detection:
          type: boolean
          description: "Boolean flag to detect and correct skewed or rotated pages in the\ndocument.\n\nSetting this to `true` will increase the processing time of the\ndocument.\n\nThe default is `false`."
          default: false
        disable_layout_detection:
          type: boolean
          description: "Disable bounding box detection for the document. Leads to faster\ndocument parsing.\n\nThe default is `false`."
          default: false
        ignore_sections:
          type: array
          items:
            $ref: "#/components/schemas/PageFragmentType"
          description: "A set of page fragment types to ignore during parsing.\n\nThis can be used to skip certain types of content that are not relevant\nfor the parsing process, such as headers, footers, or other\nnon-essential elements.\n\nThe default is an empty set."
          default: []
          uniqueItems: true
        cross_page_header_detection:
          type: boolean
          description: "Enable header-hierarchy detection across pages.\n\nWhen set to `true`, the parser will consider headers from different\npages when determining the hierarchy of headers within a single\npage.\n\nThe default is `false`."
          default: false
        include_images:
          type: boolean
          description: "Embed images from document in the markdown\n\nThe default is `false`."
          default: false
        barcode_detection:
          type: boolean
          description: "Enable barcode reader for the document.\n\nThe default is `false`."
          default: false
        merge_tables:
          type: boolean
          description: "Enable table merging for the document.\n\nWhen set to `true`, adjacent tables that are part of the same logical table will be\nmerged into a single table.\n\nThe default is `false`."
          default: false
        ocr_model:
          oneOf:
            - $ref: "#/components/schemas/OcrPipelineProvider"
              description: "The model to use for OCR (Optical Character Recognition).\n\n`model01` - It's fast but could have lower accuracy on\ncomplex tables. It's good for legal documents with footnotes.\n`model02` - It's slower but could have higher accuracy on complex\ntables. It's good for financial documents with merged cells.\n`model03` (default model) - it is our best model in terms of accuracy for business documents.\nThis model can be deployed on dedicated\nhardware in their own datacenter.\n`gemini3`\nGoogle Gemini 3 API for OCR processing."
          default: model03
      additionalProperties: false
    PartitionStrategy:
      oneOf:
        - type: string
          title: none
          description: "No partitioning is applied. The entire document is used for\nstructured data extraction."
          enum:
            - none
        - type: string
          title: page
          description: "Partition the document into pages. Each page is used for structured\ndata extraction separately."
          enum:
            - page
        - type: string
          title: section
          description: "Partition the document into sections. Each section is used for\nstructured data extraction separately.\n\nA section is defined as a group of text blocks that are visually\nseparated from other text blocks by whitespace or other visual\nelements."
          enum:
            - section
        - type: string
          title: fragment
          description: "Partition the document by fragments. Each fragment is used for\nstructured data extraction separately.\n\nA fragment is defined as a group of text blocks, images, tables, etc.\nthat are visually grouped together."
          enum:
            - fragment
        - type: object
          title: patterns
          description: "Partition the document by custom patterns. Each pattern match is used\nfor structured data extraction separately.\n\nThis requires providing start_patterns and end_patterns to define\nthe custom patterns.\n\nPatterns are defined as strings specific to the document content.\nThe start_patterns and end_patterns are used to identify the\nbeginning and end of each partition."
          required:
            - patterns
          properties:
            patterns:
              type: object
              description: "Partition the document by custom patterns. Each pattern match is used\nfor structured data extraction separately.\n\nThis requires providing start_patterns and end_patterns to define\nthe custom patterns.\n\nPatterns are defined as strings specific to the document content.\nThe start_patterns and end_patterns are used to identify the\nbeginning and end of each partition."
              required:
                - start_patterns
                - end_patterns
              properties:
                start_patterns:
                  type: array
                  items:
                    type: string
                end_patterns:
                  type: array
                  items:
                    type: string
    ReadRequest:
      allOf:
        - $ref: "#/components/schemas/RequestFileInfo"
        - $ref: "#/components/schemas/ReadRequestConfiguration"
        - type: object
          properties:
            labels:
              type:
                - object
                - "null"
              description: "Additional metadata to identify the read request. The labels are\nreturned in the read response."
              additionalProperties: {}
              propertyNames:
                type: string
              example:
                priority: high
                source: email
    ReadRequestConfiguration:
      type: object
      properties:
        parsing_options:
          $ref: "#/components/schemas/ParsingOptions"
          description: "The properties of this object define the configuration for the document\nparsing process.\n\nTensorlake provides sane defaults that work well for most\ndocuments, so this object is not required. However, every document\nis different, and you may want to customize the parsing process to\nbetter suit your needs."
        enrichment_options:
          $ref: "#/components/schemas/EnrichmentOptions"
          description: "The properties of this object help to extend the output of the document\nparsing process with additional information.\n\nThis includes summarization of tables and figures, which can help to\nprovide a more comprehensive understanding of the document.\n\nThis object is not required, and the API will use default settings if it\nis not present."
      additionalProperties: false
    RequestFileInfo:
      allOf:
        - type: object
          properties:
            page_range:
              type: string
              description: "Comma-separated list of page numbers or ranges to parse (e.g., '1,2,3-5'). Default: all pages."
              examples:
                - "1-5,8,10"
            file_name:
              type: string
              description: Name of the file. Only populated when using file_id.
              examples:
                - document.pdf
        - oneOf:
            - type: object
              title: file_id
              required:
                - file_id
              properties:
                file_id:
                  type: string
                  description: ID of the file previously uploaded to Tensorlake. Has tensorlake- (V1) or file_ (V2) prefix.
                  examples:
                    - file_abc123xyz
                mime_type:
                  type: string
                  enum:
                    - application/pdf
                    - application/vnd.openxmlformats-officedocument.wordprocessingml.document
                    - application/msword
                    - application/vnd.openxmlformats-officedocument.presentationml.presentation
                    - application/vnd.ms-powerpoint
                    - application/vnd.apple.keynote
                    - image/jpeg
                    - image/tiff
                    - text/plain
                    - text/html
                    - text/markdown
                    - text/x-markdown
                    - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
                    - application/vnd.ms-excel.sheet.macroenabled.12
                    - application/vnd.ms-excel
                    - text/xml
                    - text/csv
                    - image/png
                    - text/rtf
                    - application/rtf
                    - application/octet-stream
                    - application/pkcs7-mime
                    - application/x-pkcs7-mime
                    - application/pkcs7-signature
            - type: object
              title: file_url
              required:
                - file_url
              properties:
                file_url:
                  type: string
                  format: uri-template
                  description: External URL of the file to parse. Must be publicly accessible.
                  examples:
                    - "https://pub-226479de18b2493f96b64c6674705dd8.r2.dev/real-estate-purchase-all-signed.pdf"
                mime_type:
                  type: string
                  enum:
                    - application/pdf
                    - application/vnd.openxmlformats-officedocument.wordprocessingml.document
                    - application/msword
                    - application/vnd.openxmlformats-officedocument.presentationml.presentation
                    - application/vnd.ms-powerpoint
                    - application/vnd.apple.keynote
                    - image/jpeg
                    - image/tiff
                    - text/plain
                    - text/html
                    - text/markdown
                    - text/x-markdown
                    - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
                    - application/vnd.ms-excel.sheet.macroenabled.12
                    - application/vnd.ms-excel
                    - text/xml
                    - text/csv
                    - image/png
                    - text/rtf
                    - application/rtf
                    - application/octet-stream
                    - application/pkcs7-mime
                    - application/x-pkcs7-mime
                    - application/pkcs7-signature
            - type: object
              title: raw_text
              required:
                - raw_text
                - mime_type
              properties:
                raw_text:
                  type: string
                  description: The raw text content to parse.
                  examples:
                    - This is the document content...
                mime_type:
                  type: string
                  enum:
                    - application/pdf
                    - application/vnd.openxmlformats-officedocument.wordprocessingml.document
                    - application/msword
                    - application/vnd.openxmlformats-officedocument.presentationml.presentation
                    - application/vnd.ms-powerpoint
                    - application/vnd.apple.keynote
                    - image/jpeg
                    - image/tiff
                    - text/plain
                    - text/html
                    - text/markdown
                    - text/x-markdown
                    - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
                    - application/vnd.ms-excel.sheet.macroenabled.12
                    - application/vnd.ms-excel
                    - text/xml
                    - text/csv
                    - image/png
                    - text/rtf
                    - application/rtf
                    - application/octet-stream
                    - application/pkcs7-mime
                    - application/x-pkcs7-mime
                    - application/pkcs7-signature
          description: "File source - must be exactly one of: file_id, file_url, or raw_text"
    StructuredData:
      type: object
      required:
        - data
        - page_numbers
      properties:
        data:
          description: "The structured data extracted from the document.\n\nThis is a JSON object containing the extracted data in the\nshape of the JSON schema provided in the parse request."
        page_numbers:
          $ref: "#/components/schemas/OneOrMany_usize"
          description: "A list of page numbers (1-indexed) where the structured data was\ndetected.\n\nThe value may be a single page number or a vector of page numbers."
        schema_name:
          type:
            - string
            - "null"
          description: "The name of the schema provided in the structured extraction options of\nthe parse request.\n\nThis is used to identify the schema used for the structured data\nextraction."
    MergeTableActions:
      type: object
      required:
        - pages
      properties:
        pages:
          type: array
          items:
            type: integer
        target_columns:
          type:
            - integer
            - "null"
          default: ~
    MergedTable:
      type: object
      required:
        - merged_table_id
        - merged_table_html
        - start_page
        - end_page
        - pages_merged
        - merge_actions
      properties:
        merged_table_id:
          type: string
        merged_table_html:
          type: string
        start_page:
          type: integer
        end_page:
          type: integer
        pages_merged:
          type: integer
        summary:
          type:
            - string
            - "null"
          default: ~
        merge_actions:
          $ref: "#/components/schemas/MergeTableActions"
    StructuredExtractionOptions:
      type: object
      required:
        - schema_name
        - json_schema
      properties:
        schema_name:
          type: string
          description: "The name of the schema. This is used to tag the structured data output\nwith a name in the response."
        json_schema:
          description: "The JSON schema to guide structured data extraction from the file.\n\nThis schema should be a valid JSON schema that defines the structure of\nthe data to be extracted.\n\nThe API supports a subset of the JSON schema specification.\n\nThis value must be provided if `structured_extraction` is present in the\nrequest."
        skip_ocr:
          type: boolean
          description: "Boolean flag to skip converting the document blob to OCR text before\nstructured data extraction.\n\nIf set to `true`, the API will skip the OCR step and directly extract\nstructured data from the document.\n\nThe default is `false`."
        prompt:
          type:
            - string
            - "null"
          description: "The prompt to use for structured data extraction.\n\nIf not provided, the default prompt will be used."
        model_provider:
          $ref: "#/components/schemas/Model"
          description: "The model provider to use for structured data extraction.\n\nThe default is `tensorlake`, which uses our private model, and runs on\nour servers."
        partition_strategy:
          $ref: "#/components/schemas/PartitionStrategy"
          description: "Strategy to partition the document before structured data extraction.\nThe API will return one structured data object per partition. This is\nuseful when you want to extract certain fields from every page.\n\nOptions -\n\n* `None`(*default*) - no partitioning is applied.\n* `Page` - partition the document into pages.\n* `Section` - partition the document into sections.\nA section is defined as a group of text blocks that are visually\nseparated from other text blocks by whitespace or other visual elements.\n* `Fragment` - partition the document by fragments.\nA fragment is defined as a group of text blocks, images, tables, etc.\nthat are visually grouped together.\n* `Patterns` - partition the document by custom patterns.\nThis requires providing start_patterns and end_patterns to define the\ncustom patterns. Patterns are defined as strings specific to the\ndocument content. The start_patterns and end_patterns are used to\nidentify the beginning and end of each partition."
        page_classes:
          type:
            - array
            - "null"
          items:
            type: string
          description: "Filter the pages of the document to be used for structured data\nextraction by providing a list of page classes.\n\nThe default is `None`, which means all pages will be used."
        provide_citations:
          type:
            - boolean
            - "null"
          description: "Flag to enable visual citations in the structured data output.\nIt returns the bounding boxes of the coordinates of the document\nwhere the structured data was extracted from.\n\nThe default is `false`."
      additionalProperties: false
    TableOutputMode:
      type: string
      enum:
        - html
        - markdown
    TableParsingFormat:
      type: string
      enum:
        - tsr
        - vlm
    Usage:
      type: object
      required:
        - pages_parsed
        - signature_detected_pages
        - strikethrough_detected_pages
        - ocr_input_tokens_used
        - ocr_output_tokens_used
        - extraction_input_tokens_used
        - extraction_output_tokens_used
        - summarization_input_tokens_used
        - summarization_output_tokens_used
      properties:
        pages_parsed:
          type: integer
          format: int32
          description: "The number of pages that were parsed.\n\nThis is the total number of pages that were parsed in the document."
        signature_detected_pages:
          type: integer
          format: int32
          description: "The number of pages that had signatures detected.\n\nThis is the total number of pages that had signatures detected in the\ndocument. All pages are counted, even if multiple signatures were\ndetected on a single page, or if no signatures were detected on\nother pages.\n\nThis is only applicable if `signature_detection` was enabled in the\nparse configuration."
        strikethrough_detected_pages:
          type: integer
          format: int32
          description: "The number of pages that had were processed with strikethrough\ndetection.\n\nThis is the total number of pages that were processed with strikethrough\ndetection in the document. All pages are counted, even if no\nstrikethroughs were detected on some pages.\n\nThis is only applicable if `remove_strikethrough_lines` was enabled in\nthe parse configuration."
        ocr_input_tokens_used:
          type: integer
          format: int32
          description: The number of input tokens used for OCR.
        ocr_output_tokens_used:
          type: integer
          format: int32
          description: The number of output tokens used for OCR.
        extraction_input_tokens_used:
          type: integer
          format: int32
          description: "The number of input tokens used for structured extraction.\n\nThis will include tokens used for each JSON schema in the\n`structured_extraction_options` field of the parse configuration."
        extraction_output_tokens_used:
          type: integer
          format: int32
          description: "The number of output tokens used for structured extraction.\n\nThis will include tokens used for each JSON schema in the\n`structured_extraction_options` field of the parse configuration."
        summarization_input_tokens_used:
          type: integer
          format: int32
          description: The number of input tokens used for figure summarization.
        summarization_output_tokens_used:
          type: integer
          format: int32
          description: The number of output tokens used for figure summarization.
    SandboxProxyError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        code:
          type: string
    SandboxRuntimeHealth:
      type: object
      required:
        - healthy
      properties:
        healthy:
          type: boolean
    SandboxRuntimeInfo:
      type: object
      required:
        - version
        - uptime_secs
        - running_processes
        - total_processes
      properties:
        version:
          type: string
        uptime_secs:
          type: integer
          format: int64
        running_processes:
          type: integer
          format: int32
        total_processes:
          type: integer
          format: int32
    SandboxProcessUser:
      oneOf:
        - type: string
          description: Username, UID string, or uid:gid string.
        - type: object
          properties:
            name:
              type: string
            uid:
              type: integer
              format: int32
            gid:
              type: integer
              format: int32
    SandboxProcessStdinMode:
      type: string
      enum:
        - closed
        - pipe
    SandboxProcessOutputMode:
      type: string
      enum:
        - capture
        - discard
    SandboxProcessStatus:
      type: string
      enum:
        - running
        - exited
        - signaled
        - oom_killed
    SandboxProcessStartRequest:
      type: object
      required:
        - command
      properties:
        command:
          type: string
        args:
          type: array
          items:
            type: string
        env:
          type: object
          additionalProperties:
            type: string
        working_dir:
          type: string
        user:
          $ref: "#/components/schemas/SandboxProcessUser"
        stdin_mode:
          $ref: "#/components/schemas/SandboxProcessStdinMode"
        stdout_mode:
          $ref: "#/components/schemas/SandboxProcessOutputMode"
        stderr_mode:
          $ref: "#/components/schemas/SandboxProcessOutputMode"
    SandboxRunProcessRequest:
      type: object
      required:
        - command
      properties:
        command:
          type: string
        args:
          type: array
          items:
            type: string
        env:
          type: object
          additionalProperties:
            type: string
        working_dir:
          type: string
        user:
          $ref: "#/components/schemas/SandboxProcessUser"
        timeout:
          type: number
          format: double
          description: Maximum seconds to wait before killing the process.
    SandboxRunProcessEvent:
      description: JSON payload carried in each Server-Sent Events `data:` frame from `/api/v1/processes/run`.
      oneOf:
        - $ref: "#/components/schemas/SandboxRunProcessStartedEvent"
        - $ref: "#/components/schemas/SandboxProcessOutputEvent"
        - $ref: "#/components/schemas/SandboxRunProcessExitedEvent"
    SandboxRunProcessStartedEvent:
      type: object
      required:
        - handle
        - pid
        - started_at
      properties:
        handle:
          type: integer
          format: int64
        pid:
          type: integer
          format: int32
        started_at:
          type: integer
          format: int64
    SandboxProcessOutputEvent:
      type: object
      required:
        - line
        - timestamp
      properties:
        line:
          type: string
        timestamp:
          type: integer
          format: int64
        stream:
          type: string
          enum:
            - stdout
            - stderr
    SandboxRunProcessExitedEvent:
      type: object
      properties:
        exit_code:
          type:
            - integer
            - "null"
          format: int32
        signal:
          type:
            - integer
            - "null"
          format: int32
        oom_killed:
          type: boolean
    SandboxProcessInfo:
      type: object
      required:
        - handle
        - pid
        - status
        - stdin_writable
        - command
        - args
        - started_at
      properties:
        handle:
          type: integer
          format: int64
        pid:
          type: integer
          format: int32
        status:
          $ref: "#/components/schemas/SandboxProcessStatus"
        exit_code:
          type:
            - integer
            - "null"
          format: int32
        signal:
          type:
            - integer
            - "null"
          format: int32
        stdin_writable:
          type: boolean
        command:
          type: string
        args:
          type: array
          items:
            type: string
        started_at:
          type: integer
          format: int64
        ended_at:
          type:
            - integer
            - "null"
          format: int64
    SandboxProcessListResponse:
      type: object
      required:
        - processes
      properties:
        processes:
          type: array
          items:
            $ref: "#/components/schemas/SandboxProcessInfo"
    SandboxProcessSignalRequest:
      type: object
      required:
        - signal
      properties:
        signal:
          type: integer
          format: int32
    SandboxProcessSignalResponse:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
    SandboxProcessOutputResponse:
      type: object
      required:
        - pid
        - lines
        - line_count
      properties:
        pid:
          type: integer
          format: int32
        lines:
          type: array
          items:
            type: string
        line_count:
          type: integer
          format: int32
    SandboxPtyCreateRequest:
      type: object
      required:
        - command
      properties:
        command:
          type: string
        args:
          type: array
          items:
            type: string
        env:
          type: object
          additionalProperties:
            type: string
        working_dir:
          type: string
        rows:
          type: integer
          format: int32
        cols:
          type: integer
          format: int32
    SandboxPtyCreateResponse:
      type: object
      required:
        - session_id
        - token
      properties:
        session_id:
          type: string
        token:
          type: string
    SandboxPtySessionInfo:
      type: object
      required:
        - session_id
        - pid
        - command
        - args
        - rows
        - cols
        - created_at
        - is_alive
      properties:
        session_id:
          type: string
        pid:
          type: integer
          format: int32
        command:
          type: string
        args:
          type: array
          items:
            type: string
        rows:
          type: integer
          format: int32
        cols:
          type: integer
          format: int32
        created_at:
          type: integer
          format: int64
        ended_at:
          type:
            - integer
            - "null"
          format: int64
        exit_code:
          type:
            - integer
            - "null"
          format: int32
        is_alive:
          type: boolean
        oom_killed:
          type: boolean
          description: Included only when the kernel OOM killer terminated the PTY process.
    SandboxPtyListResponse:
      type: object
      required:
        - sessions
      properties:
        sessions:
          type: array
          items:
            $ref: "#/components/schemas/SandboxPtySessionInfo"
    SandboxPtyResizeRequest:
      type: object
      required:
        - rows
        - cols
      properties:
        rows:
          type: integer
          format: int32
        cols:
          type: integer
          format: int32
    SandboxSshEnableRequest:
      type: object
      required:
        - proxy_pubkey
      properties:
        proxy_pubkey:
          type: string
          description: OpenSSH-format public key line for the sandbox proxy backend identity.
        backend_user:
          type: string
          description: Local POSIX user that the proxy authenticates as. Defaults to tl-user.
    SandboxSshStatus:
      type: object
      required:
        - enabled
      properties:
        enabled:
          type: boolean
        pid:
          type:
            - integer
            - "null"
          format: int32
        host_key_fingerprint:
          type:
            - string
            - "null"
    SandboxDirectoryEntry:
      type: object
      required:
        - name
        - is_dir
      properties:
        name:
          type: string
        is_dir:
          type: boolean
        size:
          type:
            - integer
            - "null"
          format: int64
        modified_at:
          type:
            - integer
            - "null"
          format: int64
    SandboxDirectoryListResponse:
      type: object
      required:
        - path
        - entries
      properties:
        path:
          type: string
        entries:
          type: array
          items:
            $ref: "#/components/schemas/SandboxDirectoryEntry"
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  responses:
    UnauthorizedError:
      description: Access token is missing or invalid