openapi: 3.0.1
info:
  title: TigerGraph REST++ API
  description: >-
    Specification of the built-in TigerGraph REST++ API exposed by the TigerGraph
    database server. REST++ provides built-in endpoints to read, upsert, and delete
    vertices and edges, run installed GSQL queries as dynamic endpoints, find paths,
    retrieve schema metadata, run loading jobs, and issue bearer authentication
    tokens. By default REST++ listens on port 9000 (unified on port 14240 in
    TigerGraph 3.x and later); the GSQL server listens on port 14240. TigerGraph
    Savanna (Cloud) serves the same surface over HTTPS at a per-workspace host.
  termsOfService: https://www.tigergraph.com/legal/
  contact:
    name: TigerGraph Support
    url: https://www.tigergraph.com/support/
  version: '1.0'
servers:
  - url: http://localhost:9000
    description: Self-hosted REST++ server (default port 9000; unified on 14240 in 3.x+)
  - url: https://{workspaceId}.i.tgcloud.io:443
    description: TigerGraph Savanna (Cloud) managed workspace over HTTPS
    variables:
      workspaceId:
        default: example
        description: TigerGraph Savanna workspace identifier
security:
  - bearerAuth: []
paths:
  /api/ping:
    get:
      operationId: ping
      tags:
        - System
      summary: Health check.
      description: Returns a success response if the REST++ server is up and reachable.
      security: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestppResponse'
  /restpp/echo:
    get:
      operationId: echoGet
      tags:
        - System
      summary: Echo a request.
      description: Returns a canned response confirming the server can receive requests.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestppResponse'
    post:
      operationId: echoPost
      tags:
        - System
      summary: Echo a POST request.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestppResponse'
  /restpp/version:
    get:
      operationId: getVersion
      tags:
        - System
      summary: Show component versions.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestppResponse'
  /restpp/requesttoken:
    post:
      operationId: requestToken
      tags:
        - Authentication
      summary: Request an authentication token.
      description: >-
        Exchanges a GSQL-generated secret for a bearer authentication token. When
        token authentication is enabled, the returned token is used in the
        Authorization header for subsequent REST++ requests.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestTokenRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestTokenResponse'
  /restpp/endpoints/{graph_name}:
    get:
      operationId: listEndpoints
      tags:
        - Schema
      summary: List installed endpoints.
      description: >-
        Returns a list of built-in, dynamic (compiled GSQL query), and static
        (user-installed) endpoints and their parameters for the given graph.
      parameters:
        - $ref: '#/components/parameters/GraphName'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
  /gsql/v1/schema:
    get:
      operationId: getSchema
      tags:
        - Schema
      summary: Retrieve graph schema metadata.
      description: Returns the schema metadata (vertex types, edge types, attributes) for a graph.
      parameters:
        - in: query
          name: graph
          required: false
          schema:
            type: string
          description: Graph name to scope the schema to.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
  /restpp/ddl/{graph_name}:
    post:
      operationId: runLoadingJob
      tags:
        - Schema
      summary: Run a loading job (DDL).
      description: Ingests data into a graph using a previously defined loading job.
      parameters:
        - $ref: '#/components/parameters/GraphName'
        - in: query
          name: tag
          required: true
          schema:
            type: string
          description: Name of the loading job to run.
        - in: query
          name: filename
          required: true
          schema:
            type: string
          description: Filename variable defined in the loading job.
      requestBody:
        required: true
        content:
          text/csv:
            schema:
              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestppResponse'
  /restpp/graph/{graph_name}:
    post:
      operationId: upsertGraph
      tags:
        - Data
      summary: Upsert vertices and edges.
      description: >-
        Inserts or updates vertices and/or edges in a graph. If a vertex or edge
        does not exist it is inserted; if it exists it is updated.
      parameters:
        - $ref: '#/components/parameters/GraphName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestppResponse'
  /restpp/graph/{graph_name}/vertices/{vertex_type}:
    get:
      operationId: listVertices
      tags:
        - Data
      summary: List vertices of a type.
      description: Returns all vertices of the given type, with optional select, filter, limit, and sort.
      parameters:
        - $ref: '#/components/parameters/GraphName'
        - $ref: '#/components/parameters/VertexType'
        - $ref: '#/components/parameters/Select'
        - $ref: '#/components/parameters/Filter'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Sort'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestppResponse'
    delete:
      operationId: deleteVertices
      tags:
        - Data
      summary: Delete vertices of a type.
      parameters:
        - $ref: '#/components/parameters/GraphName'
        - $ref: '#/components/parameters/VertexType'
        - $ref: '#/components/parameters/Filter'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Sort'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestppResponse'
  /restpp/graph/{graph_name}/vertices/{vertex_type}/{vertex_id}:
    get:
      operationId: getVertex
      tags:
        - Data
      summary: Retrieve a single vertex.
      parameters:
        - $ref: '#/components/parameters/GraphName'
        - $ref: '#/components/parameters/VertexType'
        - $ref: '#/components/parameters/VertexId'
        - $ref: '#/components/parameters/Select'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestppResponse'
    delete:
      operationId: deleteVertex
      tags:
        - Data
      summary: Delete a single vertex.
      parameters:
        - $ref: '#/components/parameters/GraphName'
        - $ref: '#/components/parameters/VertexType'
        - $ref: '#/components/parameters/VertexId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestppResponse'
  /restpp/graph/{graph_name}/edges/{source_type}/{source_id}:
    get:
      operationId: listEdges
      tags:
        - Data
      summary: List edges from a source vertex.
      parameters:
        - $ref: '#/components/parameters/GraphName'
        - $ref: '#/components/parameters/SourceType'
        - $ref: '#/components/parameters/SourceId'
        - $ref: '#/components/parameters/Select'
        - $ref: '#/components/parameters/Filter'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Sort'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestppResponse'
  /restpp/graph/{graph_name}/edges/{source_type}/{source_id}/{edge_type}/{target_type}/{target_id}:
    get:
      operationId: getEdge
      tags:
        - Data
      summary: Retrieve a specific edge.
      parameters:
        - $ref: '#/components/parameters/GraphName'
        - $ref: '#/components/parameters/SourceType'
        - $ref: '#/components/parameters/SourceId'
        - $ref: '#/components/parameters/EdgeType'
        - $ref: '#/components/parameters/TargetType'
        - $ref: '#/components/parameters/TargetId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestppResponse'
    delete:
      operationId: deleteEdge
      tags:
        - Data
      summary: Delete a specific edge.
      parameters:
        - $ref: '#/components/parameters/GraphName'
        - $ref: '#/components/parameters/SourceType'
        - $ref: '#/components/parameters/SourceId'
        - $ref: '#/components/parameters/EdgeType'
        - $ref: '#/components/parameters/TargetType'
        - $ref: '#/components/parameters/TargetId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestppResponse'
  /restpp/query/{graph_name}/{query_name}:
    get:
      operationId: runInstalledQueryGet
      tags:
        - Query
      summary: Run an installed GSQL query (GET).
      description: >-
        Runs an installed GSQL query exposed as a dynamic REST++ endpoint, passing
        query parameters as URL query string parameters.
      parameters:
        - $ref: '#/components/parameters/GraphName'
        - in: path
          name: query_name
          required: true
          schema:
            type: string
          description: Name of the installed GSQL query.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestppResponse'
    post:
      operationId: runInstalledQueryPost
      tags:
        - Query
      summary: Run an installed GSQL query (POST).
      parameters:
        - $ref: '#/components/parameters/GraphName'
        - in: path
          name: query_name
          required: true
          schema:
            type: string
          description: Name of the installed GSQL query.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestppResponse'
  /restpp/interpreted_query/{graph_name}:
    post:
      operationId: runInterpretedQuery
      tags:
        - Query
      summary: Run an interpreted GSQL query.
      description: Runs a GSQL query in interpreted mode without installing it first.
      parameters:
        - $ref: '#/components/parameters/GraphName'
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestppResponse'
  /restpp/path/{graph_name}:
    get:
      operationId: shortestPath
      tags:
        - Query
      summary: Find the shortest path between vertices.
      parameters:
        - $ref: '#/components/parameters/GraphName'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestppResponse'
  /restpp/allpaths/{graph_name}:
    get:
      operationId: allPaths
      tags:
        - Query
      summary: Find all paths between vertices.
      parameters:
        - $ref: '#/components/parameters/GraphName'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestppResponse'
  /restpp/statistics/{graph_name}:
    get:
      operationId: getStatistics
      tags:
        - System
      summary: Get recent query performance statistics.
      parameters:
        - $ref: '#/components/parameters/GraphName'
        - in: query
          name: seconds
          required: false
          schema:
            type: integer
          description: Look-back window in seconds.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestppResponse'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer token obtained from POST /restpp/requesttoken (required only when
        token authentication is enabled on the TigerGraph server).
  parameters:
    GraphName:
      in: path
      name: graph_name
      required: true
      schema:
        type: string
      description: Name of the target graph.
    VertexType:
      in: path
      name: vertex_type
      required: true
      schema:
        type: string
      description: Vertex type name.
    VertexId:
      in: path
      name: vertex_id
      required: true
      schema:
        type: string
      description: Vertex primary ID.
    SourceType:
      in: path
      name: source_type
      required: true
      schema:
        type: string
    SourceId:
      in: path
      name: source_id
      required: true
      schema:
        type: string
    EdgeType:
      in: path
      name: edge_type
      required: true
      schema:
        type: string
    TargetType:
      in: path
      name: target_type
      required: true
      schema:
        type: string
    TargetId:
      in: path
      name: target_id
      required: true
      schema:
        type: string
    Select:
      in: query
      name: select
      required: false
      schema:
        type: string
      description: Comma-separated list of attributes to return.
    Filter:
      in: query
      name: filter
      required: false
      schema:
        type: string
      description: Attribute-based filter expression.
    Limit:
      in: query
      name: limit
      required: false
      schema:
        type: integer
      description: Maximum number of vertices or edges to return.
    Sort:
      in: query
      name: sort
      required: false
      schema:
        type: string
      description: Attribute to sort the results by.
  schemas:
    RestppResponse:
      type: object
      properties:
        version:
          type: object
        error:
          type: boolean
        message:
          type: string
        results:
          type: array
          items:
            type: object
    RequestTokenRequest:
      type: object
      properties:
        secret:
          type: string
          description: GSQL-generated secret.
        lifetime:
          type: string
          description: Token lifetime in seconds (default approximately one month).
      required:
        - secret
    RequestTokenResponse:
      type: object
      properties:
        code:
          type: string
          example: REST-0000
        expiration:
          type: integer
        error:
          type: boolean
        message:
          type: string
        token:
          type: string
    UpsertRequest:
      type: object
      properties:
        vertices:
          type: object
        edges:
          type: object