openapi: 3.0.0
info:
  title: NCSO Prep Knowledge API
  description: >-
    Machine-readable NCSO exam data for AI agents, partners, and integrations.
    Provides structured access to the NCSO Knowledge Graph (entities, exam facts,
    modules, requirements, tools, and pages), a practice question bank, verified
    exam facts, and LLM instructions. All data is sourced from the Alberta
    Construction Safety Association (ACSA) and the Canadian Federation of
    Construction Safety Associations (CFCSA).
  version: 1.0.0
  contact:
    name: NCSO Prep
    url: https://www.ncsoprep.ca
    email: support@ncsoprep.ca
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
  termsOfService: https://www.ncsoprep.ca/about
servers:
  - url: https://www.ncsoprep.ca
    description: Production
tags:
  - name: Knowledge Graph
    description: Complete structured data about the NCSO designation, exam, and resources.
  - name: Questions
    description: Practice questions with answers, modules, and sources.
  - name: Facts
    description: Verified exam facts with source citations.
  - name: AI
    description: Resources for AI crawlers and agents.
paths:
  /data/ncso-knowledge-graph.json:
    get:
      tags:
        - Knowledge Graph
      summary: NCSO Knowledge Graph
      description: >-
        Complete structured data about the NCSO designation, exam, requirements,
        modules, tools, and content pages. Includes entities (NCSO, ACSA, CFCSA,
        NCSO Prep), exam facts with sources, all 10 exam modules, the full
        requirements checklist, free tools, and 60+ content pages.
      operationId: getKnowledgeGraph
      responses:
        '200':
          description: The NCSO Knowledge Graph dataset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeGraph'
  /data/ncso-questions.json:
    get:
      tags:
        - Questions
      summary: NCSO Practice Questions
      description: >-
        A structured question bank of 75+ NCSO exam questions with verified
        answers, module categorization, difficulty levels, source citations, and
        links to relevant canonical pages. Covers all 10 NCSO exam modules plus
        general exam, requirements, salary, career, renewal, and comparison topics.
      operationId: getQuestions
      responses:
        '200':
          description: The NCSO practice question bank.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuestionBank'
  /data/ncso-facts.json:
    get:
      tags:
        - Facts
      summary: NCSO Exam Facts
      description: >-
        46 verified fact blocks about the NCSO exam, requirements, modules,
        salary, renewal, and comparisons. Each fact is 40-60 words with a source
        citation, source URL, and canonical page URL.
      operationId: getFacts
      responses:
        '200':
          description: The NCSO exam facts dataset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FactSet'
  /llms.txt:
    get:
      tags:
        - AI
      summary: LLM Instructions
      description: >-
        A plain-text guide for AI crawlers and agents on NCSO Prep content,
        including verified exam facts, common questions answered directly, high-intent
        question routing, and the full page index.
      operationId: getLlmsTxt
      responses:
        '200':
          description: LLM instructions in plain text.
          content:
            text/plain:
              schema:
                type: string
  /ncso-answer-engine:
    get:
      tags:
        - AI
      summary: NCSO Answer Engine
      description: >-
        A searchable page with 100+ Q&A pairs about NCSO exam topics, including
        pass mark, cost, schedule, eligibility, courses, modules, salary, and
        comparisons. Structured with FAQPage schema for machine readability.
      operationId: getAnswerEngine
      responses:
        '200':
          description: The NCSO Answer Engine page with FAQ content.
          content:
            text/html:
              schema:
                type: string
  /openapi.yaml:
    get:
      tags:
        - AI
      summary: OpenAPI Specification
      description: This OpenAPI 3.0 specification document.
      operationId: getOpenApi
      responses:
        '200':
          description: The OpenAPI YAML specification.
          content:
            application/yaml:
              schema:
                type: string
components:
  schemas:
    KnowledgeGraph:
      type: object
      properties:
        '@context':
          type: string
          example: https://schema.org
        '@type':
          type: string
          example: Dataset
        name:
          type: string
        description:
          type: string
        publisher:
          $ref: '#/components/schemas/Organization'
        datePublished:
          type: string
          format: date
        dateModified:
          type: string
          format: date
        license:
          type: string
          format: uri
        keywords:
          type: array
          items:
            type: string
        entities:
          type: array
          items:
            $ref: '#/components/schemas/Entity'
        examFacts:
          type: array
          items:
            $ref: '#/components/schemas/ExamFact'
        modules:
          type: array
          items:
            $ref: '#/components/schemas/Module'
        requirements:
          type: array
          items:
            $ref: '#/components/schemas/Requirement'
        tools:
          type: array
          items:
            $ref: '#/components/schemas/Tool'
        pages:
          type: array
          items:
            $ref: '#/components/schemas/Page'
    Organization:
      type: object
      properties:
        '@type':
          type: string
          example: Organization
        name:
          type: string
        url:
          type: string
          format: uri
        logo:
          type: string
          format: uri
    Entity:
      type: object
      properties:
        '@type':
          type: string
        name:
          type: string
        alternateName:
          type: string
        description:
          type: string
        url:
          type: string
          format: uri
    ExamFact:
      type: object
      properties:
        id:
          type: string
        topic:
          type: string
        fact:
          type: string
        value:
          type: string
        source:
          type: string
        sourceUrl:
          type: string
          format: uri
        canonicalPage:
          type: string
          format: uri
    Module:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        number:
          type: integer
        description:
          type: string
        practicePage:
          type: string
          format: uri
        freeTier:
          type: boolean
    Requirement:
      type: object
      properties:
        id:
          type: string
        category:
          type: string
        requirement:
          type: string
        details:
          type: array
          items:
            type: string
        source:
          type: string
        sourceUrl:
          type: string
          format: uri
        canonicalPage:
          type: string
          format: uri
    Tool:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        url:
          type: string
          format: uri
        description:
          type: string
        type:
          type: string
    Page:
      type: object
      properties:
        url:
          type: string
          format: uri
        title:
          type: string
        category:
          type: string
    QuestionBank:
      type: object
      properties:
        '@context':
          type: string
        '@type':
          type: string
        name:
          type: string
        totalQuestions:
          type: integer
        questions:
          type: array
          items:
            $ref: '#/components/schemas/Question'
    Question:
      type: object
      properties:
        id:
          type: string
        question:
          type: string
        answer:
          type: string
        module:
          type: string
        difficulty:
          type: string
          enum: [easy, medium, hard]
        source:
          type: string
        sourceUrl:
          type: string
          format: uri
        canonicalPage:
          type: string
          format: uri
        ctaUrl:
          type: string
          format: uri
    FactSet:
      type: object
      properties:
        '@context':
          type: string
        '@type':
          type: string
        name:
          type: string
        totalFacts:
          type: integer
        facts:
          type: array
          items:
            $ref: '#/components/schemas/Fact'
    Fact:
      type: object
      properties:
        id:
          type: string
        topic:
          type: string
        question:
          type: string
        answer:
          type: string
        source:
          type: string
        sourceUrl:
          type: string
          format: uri
        canonicalUrl:
          type: string
          format: uri
        lastReviewed:
          type: string
          format: date
