Orbital Schema Management API

openapi: 3.1.0
info:
  title: Orbital Schema Management API
  description: >-
    The Orbital Schema Management API provides endpoints for managing schemas,
    types, and data source definitions within an Orbital workspace. It allows
    developers to register, update, and remove Taxi schemas and type definitions
    that Orbital uses to understand the semantic relationships between data
    across connected services. Schemas can originate from OpenAPI specs, Protobuf
    definitions, database schemas, or Taxi projects, and are used by the TaxiQL
    query engine to automatically discover and orchestrate data fetching across
    multiple sources.
  version: 1.0.0
  contact:
    name: Orbital Support
    url: https://orbitalhq.com/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: https://localhost:9022
    description: Local Orbital Server
paths:
  /api/schemas:
    get:
      operationId: listSchemas
      summary: Orbital List schemas
      description: >-
        Returns the schemas and type definitions currently registered in the
        Orbital workspace, including types from connected API specs, database
        schemas, and Taxi projects.
      responses:
        "200":
          description: A list of schemas registered in the workspace.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SchemaEntry"
      tags:
        - Schemas
    post:
      operationId: createSchema
      summary: Orbital Register a new schema
      description: >-
        Registers a new schema in the Orbital workspace. The schema can be
        provided as a Taxi source file, OpenAPI specification, Protobuf
        definition, or other supported schema format. Orbital parses the schema,
        extracts type definitions and semantic metadata, and makes the types
        available for TaxiQL queries.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SchemaCreateRequest"
      responses:
        "201":
          description: Schema registered successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SchemaEntry"
        "400":
          description: Invalid schema definition.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      tags:
        - Schemas
  /api/schemas/{schemaId}:
    get:
      operationId: getSchema
      summary: Orbital Get a schema by ID
      description: Returns the details of a specific schema registered in the workspace.
      parameters:
        - name: schemaId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Schema details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SchemaEntry"
        "404":
          description: Schema not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      tags:
        - Schemas
    put:
      operationId: updateSchema
      summary: Orbital Update a schema
      description: >-
        Updates an existing schema in the workspace. Orbital re-parses the
        schema, updates type definitions, and refreshes the query engine's
        understanding of available data sources.
      parameters:
        - name: schemaId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SchemaCreateRequest"
      responses:
        "200":
          description: Schema updated successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SchemaEntry"
        "400":
          description: Invalid schema definition.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Schema not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      tags:
        - Schemas
    delete:
      operationId: deleteSchema
      summary: Orbital Delete a schema
      description: >-
        Removes a schema and its associated type definitions from the workspace.
        Types that are only defined in this schema will no longer be available
        for TaxiQL queries.
      parameters:
        - name: schemaId
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Schema deleted successfully.
        "404":
          description: Schema not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      tags:
        - Schemas
  /api/types:
    get:
      operationId: listTypes
      summary: Orbital List registered types
      description: >-
        Returns all semantic types registered in the Orbital workspace from
        connected API specs, database schemas, and Taxi projects.
      responses:
        "200":
          description: A list of registered types.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TypeEntry"
      tags:
        - Types
  /api/types/{qualifiedName}:
    get:
      operationId: getType
      summary: Orbital Get type details
      description: >-
        Returns detailed information about a specific semantic type, including
        its definition, the sources that expose it, and the fields it contains.
      parameters:
        - name: qualifiedName
          in: path
          required: true
          description: Fully qualified name of the type.
          schema:
            type: string
      responses:
        "200":
          description: Type details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TypeDetail"
        "404":
          description: Type not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      tags:
        - Types
  /api/services:
    get:
      operationId: listServices
      summary: Orbital List connected services
      description: >-
        Returns the list of services currently connected to Orbital, including
        REST APIs, databases, message queues, and serverless functions.
      responses:
        "200":
          description: A list of connected services.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ServiceEntry"
      tags:
        - Services
  /api/services/{serviceName}:
    get:
      operationId: getService
      summary: Orbital Get service details
      description: >-
        Returns detailed information about a specific connected service,
        including its operations, types, and connection status.
      parameters:
        - name: serviceName
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Service details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceDetail"
        "404":
          description: Service not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      tags:
        - Services
components:
  schemas:
    SchemaEntry:
      type: object
      description: A schema registered in the Orbital workspace.
      properties:
        id:
          type: string
          description: Unique identifier for the schema.
        name:
          type: string
          description: Human-readable name of the schema.
        version:
          type: string
          description: Version of the schema.
        source:
          type: string
          description: Source format of the schema.
          enum:
            - TAXI
            - OPEN_API
            - PROTOBUF
            - AVRO
            - JSON_SCHEMA
            - DATABASE
        content:
          type: string
          description: The raw schema content.
        types:
          type: array
          description: Types defined in this schema.
          items:
            type: string
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the schema was registered.
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the schema was last updated.
    SchemaCreateRequest:
      type: object
      description: Request body for registering or updating a schema.
      required:
        - name
        - source
        - content
      properties:
        name:
          type: string
          description: Human-readable name for the schema.
        source:
          type: string
          description: Format of the schema being registered.
          enum:
            - TAXI
            - OPEN_API
            - PROTOBUF
            - AVRO
            - JSON_SCHEMA
            - DATABASE
        content:
          type: string
          description: >-
            The raw schema content. For OpenAPI, provide the YAML or JSON spec.
            For Taxi, provide the .taxi source. For Protobuf, provide the .proto
            definition.
        url:
          type: string
          format: uri
          description: >-
            Optional URL to load the schema from instead of providing content
            inline.
    TypeEntry:
      type: object
      description: A semantic type registered in the workspace.
      properties:
        qualifiedName:
          type: string
          description: Fully qualified name of the type.
        kind:
          type: string
          description: Kind of type definition.
          enum:
            - SCALAR
            - MODEL
            - ENUM
            - SERVICE
        sources:
          type: array
          description: Data sources that expose this type.
          items:
            type: string
    TypeDetail:
      type: object
      description: Detailed information about a semantic type.
      properties:
        qualifiedName:
          type: string
          description: Fully qualified name of the type.
        kind:
          type: string
          description: Kind of type definition.
          enum:
            - SCALAR
            - MODEL
            - ENUM
            - SERVICE
        fields:
          type: array
          description: Fields defined on this type (for MODEL types).
          items:
            type: object
            properties:
              name:
                type: string
                description: Field name.
              type:
                type: string
                description: Qualified type name of the field.
              nullable:
                type: boolean
                description: Whether the field is nullable.
        sources:
          type: array
          description: Data sources that expose this type.
          items:
            type: string
        schemaId:
          type: string
          description: ID of the schema that defines this type.
    ServiceEntry:
      type: object
      description: A service connected to Orbital.
      properties:
        name:
          type: string
          description: Name of the service.
        url:
          type: string
          format: uri
          description: Base URL of the service.
        protocol:
          type: string
          description: Protocol type of the service.
          enum:
            - REST
            - gRPC
            - SOAP
            - Kafka
            - Database
        operationCount:
          type: integer
          description: Number of operations exposed by this service.
        status:
          type: string
          description: Current connection status of the service.
          enum:
            - CONNECTED
            - DISCONNECTED
            - ERROR
    ServiceDetail:
      type: object
      description: Detailed information about a connected service.
      properties:
        name:
          type: string
          description: Name of the service.
        url:
          type: string
          format: uri
          description: Base URL of the service.
        protocol:
          type: string
          description: Protocol type of the service.
          enum:
            - REST
            - gRPC
            - SOAP
            - Kafka
            - Database
        status:
          type: string
          description: Current connection status.
          enum:
            - CONNECTED
            - DISCONNECTED
            - ERROR
        operations:
          type: array
          description: Operations exposed by this service.
          items:
            type: object
            properties:
              name:
                type: string
                description: Operation name.
              returnType:
                type: string
                description: Qualified type name of the return type.
              parameters:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    type:
                      type: string
        types:
          type: array
          description: Types exposed by this service.
          items:
            type: string
    ErrorResponse:
      type: object
      description: Error response from the Orbital API.
      properties:
        message:
          type: string
          description: Human-readable error message.
        code:
          type: string
          description: Error code identifying the type of error.
        details:
          type: object
          description: Additional error details.
          additionalProperties: true
tags:
  - name: Schemas
  - name: Services
  - name: Types