openapi: 3.0.3
info:
  title: RTOFlow API Preview
  version: "1.0.0-preview"
  summary: Preview API surface for approved RTOFlow document-generation integrations.
  description: |
    RTOFlow is an AI-assisted training and assessment resource generation
    platform for Australian Registered Training Organisations (RTOs).

    This OpenAPI document describes the preview integration surface for
    approved developer, automation, and AI-agent workflows. Public API access
    requires an issued API key and an approved use case. The spec is published
    for agent discoverability and integration planning; this preview spec keeps
    access controlled rather than open-ended.

    Generated documents are mapped drafts designed to support audit readiness
    against training.gov.au data and the Standards for RTOs 2025. They require
    qualified practitioner review, contextualisation, and validation before use.
  termsOfService: https://rtoflow.au/terms
  contact:
    name: RTOFlow Developer Support
    url: https://rtoflow.au/developers
    email: hello@rtoflow.au
  license:
    name: Proprietary
    url: https://rtoflow.au/terms
servers:
  - url: https://api.rtoflow.au/v1
    description: Preview API base URL for approved integrations
security:
  - bearerAuth: []
tags:
  - name: generate
    description: Preview document generation jobs
  - name: units
    description: training.gov.au unit lookup metadata
  - name: jobs
    description: Async generation job status
paths:
  /generate/learner-guide:
    post:
      tags: [generate]
      summary: Generate a learner guide draft
      operationId: generateLearnerGuide
      description: |
        Queue generation of a learner guide draft from a training.gov.au unit
        code. Returns an async job identifier. The generated output must be
        reviewed and contextualised by the RTO before use.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GenerateRequest"
            example:
              unit_code: BSBWHS411
              format: docx
              rto_name: Example RTO Pty Ltd
              industry_context: construction
      responses:
        "202":
          description: Generation job accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/UnitNotFound"
  /generate/assessment:
    post:
      tags: [generate]
      summary: Generate an assessment workbook draft
      operationId: generateAssessmentWorkbook
      description: |
        Queue generation of an assessment workbook draft mapped to the unit's
        performance evidence, knowledge evidence, and assessment conditions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GenerateRequest"
      responses:
        "202":
          description: Generation job accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/UnitNotFound"
  /generate/observation-checklist:
    post:
      tags: [generate]
      summary: Generate an observation checklist draft
      operationId: generateObservationChecklist
      description: |
        Queue generation of an observation checklist draft that turns unit
        performance criteria into observable assessor prompts and benchmarks.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GenerateRequest"
      responses:
        "202":
          description: Generation job accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/UnitNotFound"
  /generate/mapping-matrix:
    post:
      tags: [generate]
      summary: Generate a mapping matrix draft
      operationId: generateMappingMatrix
      description: |
        Queue generation of a mapping matrix draft that cross-references tasks
        and evidence prompts against source unit requirements.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GenerateRequest"
      responses:
        "202":
          description: Generation job accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/UnitNotFound"
  /generate/rpl-kit:
    post:
      tags: [generate]
      summary: Generate an RPL evidence kit draft
      operationId: generateRplKit
      description: |
        Queue generation of a Recognition of Prior Learning evidence kit draft
        for the supplied unit code.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GenerateRequest"
      responses:
        "202":
          description: Generation job accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/UnitNotFound"
  /generate/full-suite:
    post:
      tags: [generate]
      summary: Generate a full resource suite draft
      operationId: generateFullSuite
      description: |
        Queue generation of a coordinated draft resource suite for a unit,
        including learner-facing, assessor-facing, mapping, and RPL artefacts
        where supported by the customer's plan and scope.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GenerateRequest"
      responses:
        "202":
          description: Generation job accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/UnitNotFound"
  /units/search:
    get:
      tags: [units]
      summary: Search training.gov.au unit metadata
      operationId: searchUnits
      parameters:
        - name: q
          in: query
          required: true
          description: Unit code or keyword.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
      responses:
        "200":
          description: Matching units
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/UnitSummary"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /units/{unit_code}:
    get:
      tags: [units]
      summary: Retrieve unit metadata
      operationId: getUnit
      parameters:
        - name: unit_code
          in: path
          required: true
          schema:
            type: string
          example: BSBWHS411
      responses:
        "200":
          description: Unit metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnitDetail"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/UnitNotFound"
  /jobs/{job_id}:
    get:
      tags: [jobs]
      summary: Poll generation job status
      operationId: getJob
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Job status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobStatus"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: Job not found
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
  schemas:
    GenerateRequest:
      type: object
      required:
        - unit_code
        - format
      properties:
        unit_code:
          type: string
          description: training.gov.au unit code.
          example: BSBWHS411
        format:
          type: string
          enum: [docx, pdf]
          default: docx
        rto_name:
          type: string
          description: Optional organisation name to include in generated drafts.
        rto_code:
          type: string
          description: Optional national provider identifier.
        industry_context:
          type: string
          description: Optional industry or learner cohort context.
        branding_profile_id:
          type: string
          description: Optional approved branding profile identifier.
    JobResponse:
      type: object
      required: [job_id, status]
      properties:
        job_id:
          type: string
          example: job_01HYRTOFLOW7Q8Z
        status:
          type: string
          enum: [queued, running, complete, failed]
          example: queued
        poll_url:
          type: string
          example: /v1/jobs/job_01HYRTOFLOW7Q8Z
    JobStatus:
      type: object
      required: [job_id, status]
      properties:
        job_id:
          type: string
        status:
          type: string
          enum: [queued, running, complete, failed]
        progress_percent:
          type: integer
          minimum: 0
          maximum: 100
        download_url:
          type: string
          nullable: true
        failure_reason:
          type: string
          nullable: true
    UnitSummary:
      type: object
      required: [code, title]
      properties:
        code:
          type: string
          example: BSBWHS411
        title:
          type: string
          example: Implement and monitor WHS policies, procedures and programs
        training_package:
          type: string
          nullable: true
    UnitDetail:
      allOf:
        - $ref: "#/components/schemas/UnitSummary"
        - type: object
          properties:
            elements:
              type: array
              items:
                type: string
            performance_criteria:
              type: array
              items:
                type: string
            knowledge_evidence:
              type: array
              items:
                type: string
            performance_evidence:
              type: array
              items:
                type: string
            assessment_conditions:
              type: array
              items:
                type: string
            source_url:
              type: string
              example: https://training.gov.au/Training/Details/BSBWHS411
    Error:
      type: object
      required: [detail]
      properties:
        detail:
          type: string
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    UnitNotFound:
      description: Unit not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
x-rtoflow-status: preview_request_access
x-rtoflow-human-review-required: true
