AI Certificates Readiness API

openapi: 3.2.0
info:
  title: AI Certificates public Readiness API
  version: 1.0.0
  summary: Practice-exam readiness data and guide sources for the Claude certifications.
  description: 'AI Certificates publishes original practice questions and study guides for the four

    Anthropic Claude certifications (CCAR-P, CCAR-F, CCDV-F, CCAO-F).


    This API is read-mostly and unauthenticated. Use it to read published cohort

    statistics for the readiness check, and to fetch any study guide as markdown

    instead of scraping the HTML.


    Exams:

    - `ccar-p` — Claude Certified Architect — Professional (CCAR-P), 63 items, fee $175 USD

    - `ccdv-f` — Claude Certified Developer — Foundations (CCDV-F), 53 items, fee $125 USD

    - `ccao-f` — Claude Certified Associate — Foundations (CCAO-F), 60 items, fee $99 USD

    - `ccar-f` — Claude Certified Architect — Foundations (CCAR-F), 60 items, fee $125 USD


    The readiness quiz is 12 questions; 8 answered is the minimum for a percentile.


    Every page also negotiates content: send `Accept: text/markdown` to a guide URL

    and you get the markdown source. Responses carry `Vary: Accept`.'
  contact:
    name: Matthew Hartman
    url: https://aicertificates.study/contact
  license:
    name: All rights reserved
    url: https://aicertificates.study/privacy
servers:
- url: https://aicertificates.study
  description: Production
tags:
- name: Readiness
  description: The 12-question readiness check and its cohort statistics
paths:
  /api/readiness-stats:
    get:
      tags:
      - Readiness
      operationId: getReadinessStats
      summary: Published cohort statistics for every exam
      description: 'Aggregate statistics for the current monthly cohort, one entry per exam. Cached for 5 minutes at the edge. An exam with too few attempts to publish honestly returns `{ show: false }` rather than a fabricated aggregate — treat `show` as the gate on every other field. No parameters: one fetch serves every exam, and each entry names its own cohort.'
      responses:
        '200':
          description: Cohort statistics, keyed by exam slug.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadinessStats'
  /api/readiness-token:
    get:
      tags:
      - Readiness
      operationId: mintReadinessToken
      summary: Mint a submit token for a readiness attempt
      description: Returns a short-lived token that proves elapsed time between starting and submitting a readiness check. It is a friction layer, not authentication. Rate limited to 10 mints per minute per address.
      parameters:
      - name: exam
        in: query
        required: true
        description: Exam slug.
        schema:
          type: string
          enum:
          - ccar-p
          - ccdv-f
          - ccao-f
          - ccar-f
      responses:
        '200':
          description: A minted token.
          content:
            application/json:
              schema:
                type: object
                required:
                - token
                properties:
                  token:
                    type: string
        '400':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
components:
  schemas:
    ExamStats:
      type: object
      required:
      - show
      description: '`show: false` means too few attempts to publish; no other field is present.'
      properties:
        show:
          type: boolean
        cohortKey:
          type: string
          description: Cohort month, e.g. "2026-08".
        cohortCount:
          type: integer
          description: Counted attempts in the cohort.
        median:
          type: integer
          description: Median score out of 12.
    ReadinessStats:
      type: object
      required:
      - exams
      properties:
        exams:
          type: object
          description: Keyed by exam slug.
          additionalProperties:
            $ref: '#/components/schemas/ExamStats'
    Error:
      type: object
      required:
      - error
      - code
      - message
      - hint
      - retryable
      properties:
        error:
          type: string
          description: Legacy string code. Prefer `code`.
        code:
          type: string
          enum:
          - not_configured
          - bad_request
          - bad_json
          - unknown_exam
          - rate_limited
          - unavailable
          - send_failed
          - not_found
          - not_signed_in
          - session_stale
          - already_entitled
          - payments_unavailable
          - single_unavailable
          - seats_unavailable
          - bad_quantity
          - checkout_failed
        message:
          type: string
          description: Human-readable description of what went wrong.
        hint:
          type: string
          description: What to do about it.
        retryable:
          type: boolean
          description: Whether retrying with backoff can succeed.
  responses:
    Error:
      description: A structured error. `retryable` says whether backing off will help.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
externalDocs:
  description: Developer and agent reference
  url: https://aicertificates.study/developers