openapi: 3.0.3
info:
  title: Roadie Catalog API
  description: Roadie is a managed (SaaS) Backstage - a hosted internal developer portal and software catalog. This document models Roadie's public REST API surface exposed under https://api.roadie.so/api. It covers the software catalog (reading Backstage entities and pushing Roadie-managed entities and entity sets), the Scaffolder (Backstage software templates / self-service golden paths), Tech Insights (facts, checks, and scorecards), and TechDocs (technical documentation) surfaces. All requests are authenticated with a Bearer token (User Token or Service Token) created in the Roadie Administration UI. The Roadie public API is available on Cloud Hosted Roadie. Catalog read endpoints follow the upstream Backstage Software Catalog API shape; the roadie-entities and entity-set endpoints are Roadie's own ingestion API. Request/response schemas here are modeled from Roadie and Backstage documentation and should be reconciled against the interactive reference at https://roadie.io/docs/api/overview/ before relying on exact field names. TechDocs endpoints follow the Backstage TechDocs API and are modeled; confirm availability on your Roadie tenant.
  version: '1.0'
  contact:
    name: Roadie (Larder Software Limited)
    url: https://roadie.io
  x-modeled: Base URLs and auth are confirmed from Roadie documentation. Individual request/response schemas are modeled from Roadie + Backstage docs and are not a Roadie-published OpenAPI file.
servers:
- url: https://api.roadie.so/api
  description: Roadie Cloud Hosted API
security:
- bearerAuth: []
tags:
- name: Catalog
  description: Read Backstage software catalog entities in your Roadie tenant.
paths:
  /catalog/entities:
    get:
      operationId: listCatalogEntities
      tags:
      - Catalog
      summary: List catalog entities
      description: Lists software catalog entities (Components, APIs, Systems, Resources, Groups, Users, Templates, and more) in your Roadie tenant. Supports Backstage-style filter, fields, offset, and limit query parameters.
      parameters:
      - name: filter
        in: query
        required: false
        description: Backstage entity filter, e.g. kind=component,spec.type=service.
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: Comma-separated list of entity fields to return.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: offset
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: A list of catalog entities.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Entity'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /catalog/entities/by-query:
    get:
      operationId: queryCatalogEntities
      tags:
      - Catalog
      summary: Query catalog entities
      description: Paginated, filterable query over catalog entities returning items plus a cursor for the next page. Mirrors the Backstage entities/by-query endpoint.
      parameters:
      - name: filter
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A page of catalog entities.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Entity'
                  pageInfo:
                    type: object
                    properties:
                      nextCursor:
                        type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /catalog/entities/by-name/{kind}/{namespace}/{name}:
    get:
      operationId: getCatalogEntityByName
      tags:
      - Catalog
      summary: Get a catalog entity by name
      description: Retrieves a single catalog entity by its kind, namespace, and name.
      parameters:
      - $ref: '#/components/parameters/Kind'
      - $ref: '#/components/parameters/Namespace'
      - $ref: '#/components/parameters/Name'
      responses:
        '200':
          description: The requested catalog entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /catalog/entity-facets:
    get:
      operationId: getEntityFacets
      tags:
      - Catalog
      summary: Get entity facets
      description: Returns counts of entities grouped by one or more facets (for example spec.type or metadata.tags), useful for building catalog filters.
      parameters:
      - name: facet
        in: query
        required: true
        description: Facet path to aggregate on, e.g. kind or spec.type.
        schema:
          type: string
      - name: filter
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Facet counts.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    Kind:
      name: kind
      in: path
      required: true
      description: Entity kind, e.g. component, api, system, group, user, template.
      schema:
        type: string
    Namespace:
      name: namespace
      in: path
      required: true
      description: Entity namespace, typically default.
      schema:
        type: string
    Name:
      name: name
      in: path
      required: true
      description: Entity name.
      schema:
        type: string
  schemas:
    Entity:
      type: object
      description: A Backstage-format catalog entity.
      properties:
        apiVersion:
          type: string
          example: backstage.io/v1alpha1
        kind:
          type: string
          example: Component
        metadata:
          type: object
          properties:
            name:
              type: string
            namespace:
              type: string
            title:
              type: string
            description:
              type: string
            tags:
              type: array
              items:
                type: string
            annotations:
              type: object
              additionalProperties:
                type: string
          additionalProperties: true
        spec:
          type: object
          additionalProperties: true
        relations:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            name:
              type: string
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid Bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Roadie API token (User Token or Service Token) created under Administration in the Roadie app. Passed as `Authorization: Bearer YOUR_ROADIE_API_TOKEN`.'