openapi: 3.1.0
info:
  title: AI Builder Hub API for Rakyat Digital
  version: 1.0.0
  description: >-
    What RD reads from the AI Builder Hub: one learner's figures for the dashboard card (RD's server key), and public
    featured projects, upcoming events and totals for RD's AI Builder page (no key). No record sync. See the
    integration guide for the rules on RD's side.
servers:
  - url: https://rd-hub-248055939850.asia-southeast1.run.app
    description: Sandbox (the Hub's preview, demo data only)
  - url: https://{production_host}
    description: Production, to be confirmed
    variables:
      production_host:
        default: to-be-confirmed.example
components:
  securitySchemes:
    rdServerKey:
      type: http
      scheme: bearer
      description: RD's server key, one per environment, sent only in the Authorization header. Never a learner's key.
  headers:
    RequestId:
      description: The request's id; quote it when reporting a problem.
      schema: { type: string }
  schemas:
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message, request_id]
          properties:
            code:
              type: string
              examples: [unauthenticated, not_found, method_not_allowed, validation_failed, too_many_requests, server_error, service_unavailable]
            message: { type: string }
            request_id: { type: string }
            fields:
              type: object
              description: On 422 only. Each failed field or parameter, with the names of the rules it failed.
              additionalProperties: { type: array, items: { type: string } }
    BuilderSummaryLinked:
      type: object
      required: [linked, username, is_listed, profile_url, start_url, level, projects_shipped, events_joined]
      properties:
        linked: { const: true }
        username: { type: string }
        is_listed: { type: boolean, description: Public by the builder's choice, not hidden, not suspended. }
        profile_url: { type: [string, 'null'], format: uri, description: Null unless is_listed. }
        start_url: { type: string, format: uri, description: "The card's arrow. Use as given." }
        level: { type: integer, minimum: 1 }
        projects_shipped: { type: integer, minimum: 0, description: Published projects, public and private. }
        events_joined: { type: integer, minimum: 0, description: Events joined and not left. }
    BuilderSummaryNotLinked:
      type: object
      required: [linked, start_url]
      properties:
        linked: { const: false }
        start_url: { type: string, format: uri }
    NamedRef:
      type: object
      required: [slug, name]
      properties:
        slug: { type: string }
        name: { type: string }
    State:
      type: object
      required: [code, name]
      properties:
        code: { type: string, pattern: '^MY-(0[1-9]|1[0-6])$' }
        name: { type: string }
    ProjectType:
      type: [string, 'null']
      enum: [agriculture, education, health, fintech, transport, environment, small_business, tourism, culture, civic,
             accessibility, safety, productivity, games, other, null]
      description: Null on a project imported or made before types existed, until its owner edits it.
    ProjectCard:
      type: object
      required: [slug, title, summary, project_type, cover_url, skills, source, is_featured, builder, published_at]
      properties:
        slug: { type: string, description: 'Link to https://<hub>/projects/<slug>.' }
        title: { type: string, maxLength: 80 }
        summary: { type: [string, 'null'], maxLength: 160 }
        project_type: { $ref: '#/components/schemas/ProjectType' }
        cover_url: { type: [string, 'null'], format: uri }
        skills: { type: array, items: { $ref: '#/components/schemas/NamedRef' } }
        source: { type: string, enum: [git, manual] }
        is_featured: { type: boolean }
        builder:
          type: object
          required: [username, avatar_url, is_verified]
          properties:
            username: { type: string }
            avatar_url: { type: [string, 'null'], format: uri }
            is_verified: { type: boolean }
        published_at: { type: string, format: date-time }
    Event:
      type: object
      required: [source, slug, title, description, event_type, start_at, end_at, is_online, location, state,
                 organizer_name, tags, banner_url, kd_url, external_url, is_featured, is_started, is_past]
      properties:
        source: { type: string, enum: [hub, kd], description: 'hub: the Hub''s own event. kd: a Builder Community event from the KrackedDevs feed.' }
        slug: { type: string, description: 'Link to https://<hub>/events/<source>/<slug>.' }
        title: { type: string }
        description: { type: [string, 'null'] }
        event_type: { type: [string, 'null'], description: 'Hub events: workshop, hackathon, meetup, conference, webinar or other. Community events: the feed''s own text.' }
        start_at: { type: string, format: date-time }
        end_at: { type: [string, 'null'], format: date-time }
        is_online: { type: boolean }
        location: { type: [string, 'null'] }
        state: { oneOf: [{ $ref: '#/components/schemas/State' }, { type: 'null' }] }
        organizer_name: { type: [string, 'null'] }
        tags: { type: array, items: { type: string } }
        banner_url: { type: [string, 'null'], format: uri }
        kd_url: { type: [string, 'null'], format: uri }
        external_url: { type: [string, 'null'], format: uri }
        is_featured: { type: boolean }
        is_started: { type: boolean }
        is_past: { type: boolean }
  responses:
    Unauthenticated:
      description: No key, a wrong key, or a key in the URL. Every refusal gets this same answer.
      content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
    TooManyRequests:
      description: Over a limit, or 10 refused calls in a minute from this address. Wait the Retry-After seconds.
      headers:
        Retry-After: { schema: { type: integer } }
      content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
    ValidationFailed:
      description: A header or parameter failed a rule; see error.fields. No value you sent is echoed.
      content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } }
paths:
  /api/sync/v1/builder-summary:
    get:
      operationId: getBuilderSummary
      summary: One learner's figures for the dashboard card
      description: >-
        Call from RD's server only. Take the sub from the learner's own server-side session, never from the browser;
        cache each answer per learner for a few minutes. Any query parameter is refused.
      security: [{ rdServerKey: [] }]
      parameters:
        - name: X-Mydid-Sub
          in: header
          required: true
          description: "The learner's MyDigital ID `sub` from RD's own sign-in session. Never in the URL."
          schema: { type: string, minLength: 1, maxLength: 255 }
      responses:
        '200':
          description: Linked or not linked. Cache-Control no-store.
          headers:
            X-Request-Id: { $ref: '#/components/headers/RequestId' }
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    oneOf:
                      - $ref: '#/components/schemas/BuilderSummaryLinked'
                      - $ref: '#/components/schemas/BuilderSummaryNotLinked'
              examples:
                linked:
                  value:
                    data:
                      linked: true
                      username: aisyah-builds
                      is_listed: true
                      profile_url: https://rd-hub-248055939850.asia-southeast1.run.app/builders/aisyah-builds
                      start_url: https://rd-hub-248055939850.asia-southeast1.run.app/login
                      level: 2
                      projects_shipped: 3
                      events_joined: 4
                notLinked:
                  value: { data: { linked: false, start_url: 'https://rd-hub-248055939850.asia-southeast1.run.app/login' } }
        '401': { $ref: '#/components/responses/Unauthenticated' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
  /api/home:
    get:
      operationId: getHome
      summary: Featured projects (and the Hub home's project band)
      description: >-
        Public. featured_projects holds up to 5 featured public projects with a cover, newest featured first.
        projects (up to 8) and project_types (up to 5) are the Hub home's band; RD may ignore them. Cache 1 to 5 minutes.
      security: []
      responses:
        '200':
          description: The home content.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [featured_projects, projects, project_types]
                    properties:
                      featured_projects: { type: array, maxItems: 5, items: { $ref: '#/components/schemas/ProjectCard' } }
                      projects: { type: array, maxItems: 8, items: { $ref: '#/components/schemas/ProjectCard' } }
                      project_types: { type: array, maxItems: 5, items: { type: string } }
        '429': { $ref: '#/components/responses/TooManyRequests' }
  /api/projects:
    get:
      operationId: listProjects
      summary: Public projects, paginated (optional for RD)
      description: Public. Featured first (newest featured), then newest published. Use featured=true for featured only.
      security: []
      parameters:
        - { name: featured, in: query, schema: { type: string, enum: ['true', 'false'] } }
        - { name: project_type, in: query, schema: { type: string } }
        - { name: q, in: query, description: Search title, summary and problem., schema: { type: string, maxLength: 80 } }
        - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
        - { name: per_page, in: query, description: Above 50 is served as 50., schema: { type: integer, minimum: 1, default: 20 } }
      responses:
        '200':
          description: One page of projects.
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/ProjectCard' } }
                  meta:
                    type: object
                    required: [page, per_page, total, last_page, types_in_use, featured_in_use]
                    properties:
                      page: { type: integer }
                      per_page: { type: integer }
                      total: { type: integer }
                      last_page: { type: integer }
                      types_in_use: { type: array, items: { type: string } }
                      featured_in_use: { type: boolean }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
  /api/events:
    get:
      operationId: listEvents
      summary: Upcoming events, featured ones marked
      description: Public. Events not yet ended, soonest first. Cache 1 to 5 minutes. No CORS; call from RD's server.
      security: []
      parameters:
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 50, default: 50 }
        - name: month
          in: query
          description: YYYY-MM in Malaysia time, up to six months ahead.
          schema: { type: string, pattern: '^\d{4}-\d{2}$' }
      responses:
        '200':
          description: The events.
          content:
            application/json:
              schema:
                type: object
                required: [data, meta]
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/Event' } }
                  meta:
                    type: object
                    required: [fetched_at, stale, kd_available]
                    properties:
                      fetched_at: { type: [string, 'null'], format: date-time }
                      stale: { type: boolean }
                      kd_available: { type: boolean }
        '422': { $ref: '#/components/responses/ValidationFailed' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
  /api/stats:
    get:
      operationId: getStats
      summary: Hub totals
      description: Public. Publicly visible builders, public projects and upcoming events. Recounted every 60 seconds.
      security: []
      responses:
        '200':
          description: The totals.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: object
                    required: [builders_count, projects_count, upcoming_events_count, computed_at]
                    properties:
                      builders_count: { type: integer }
                      projects_count: { type: integer }
                      upcoming_events_count: { type: integer }
                      computed_at: { type: string, format: date-time }
        '429': { $ref: '#/components/responses/TooManyRequests' }