openapi: 3.0.3
info:
  title: Roadie Catalog Tech Insights 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: Tech Insights
  description: Facts, checks, and scorecards describing entity quality and compliance.
paths:
  /tech-insights/v1/facts:
    get:
      operationId: listTechInsightsFacts
      tags:
      - Tech Insights
      summary: Retrieve facts for entities
      description: Returns collected Tech Insights facts (raw signals such as presence of an owner, README, or a passing pipeline) for one or more entities.
      parameters:
      - name: entity
        in: query
        required: false
        description: Entity reference to scope facts to, e.g. component:default/my-service.
        schema:
          type: string
      responses:
        '200':
          description: Facts keyed by fact id.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /tech-insights/v1/checks:
    get:
      operationId: listTechInsightsChecks
      tags:
      - Tech Insights
      summary: List defined checks
      description: Lists the Tech Insights checks (boolean assertions over facts) defined in the tenant.
      responses:
        '200':
          description: A list of checks.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /tech-insights/v1/checks/run:
    post:
      operationId: runTechInsightsChecks
      tags:
      - Tech Insights
      summary: Run checks against entities
      description: Evaluates one or more checks against the supplied entities and returns pass/fail results.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                entities:
                  type: array
                  items:
                    type: string
                checks:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Check results.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /tech-insights/v1/scorecards:
    get:
      operationId: listScorecards
      tags:
      - Tech Insights
      summary: List scorecards
      description: Returns Tech Insights scorecards - grouped sets of checks that measure maturity, security, or ownership quality across the software catalog.
      responses:
        '200':
          description: A list of scorecards.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            name:
              type: string
  responses:
    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`.'