Codequiry Checks API

openapi: 3.2.0
info:
  title: Codequiry Com Checks API
  version: 1.0.0
  contact:
    name: Codequiry Support
    url: https://codequiry.com/contact
  license:
    name: Proprietary
    url: https://codequiry.com/terms-of-service
  description: 'Operations tagged Checks across 2 of this provider''s published API definitions: codequiry-com-openapi-original.json, codequiry-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://codequiry.com/api/v1
  description: Production
security:
- apikey: []
tags:
- name: Checks
  description: Create, list, update, and delete checks.
paths:
  /checks:
    get:
      tags:
      - Checks
      operationId: listChecks
      summary: List your checks
      description: Returns every check (assignment) owned by the account, newest first, each with its status object. Unpaged by default for backwards compatibility; pass `limit` (and optionally `offset`) to page through a large account instead of pulling every check on each call.
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          example: 25
          minimum: 1
          maximum: 500
        description: Maximum checks to return. Omit for all of them.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
        description: Checks to skip, newest first. Supplying offset without limit caps the page at 500.
      - name: with_stats
        in: query
        required: false
        schema:
          type: boolean
          example: true
        description: 'Attach a `stats` object to every check: submission counts, mean and max Group/Web/AI scores over finished submissions, flagged counts and the match total, so a list screen needs no per-check calls.'
      responses:
        '200':
          description: Array of checks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Check'
        '401':
          $ref: '#/components/responses/InvalidKey'
        '402':
          $ref: '#/components/responses/BillingSuspended'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      tags:
      - Checks
      operationId: listChecksPost
      summary: List your checks (POST)
      description: Identical to the GET form; `limit` and `offset` may be sent in the body.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                limit:
                  type: integer
                  example: 25
                  minimum: 1
                  maximum: 500
                offset:
                  type: integer
                  example: 0
                  minimum: 0
                with_stats:
                  type: boolean
                  example: true
                  description: Attach a `stats` object to every check (see the GET form).
      responses:
        '200':
          description: Array of checks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Check'
        '401':
          $ref: '#/components/responses/InvalidKey'
        '402':
          $ref: '#/components/responses/BillingSuspended'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://codequiry.com/api/v1
      description: Production
  /check/create:
    post:
      tags:
      - Checks
      operationId: createCheck
      summary: Create a check
      description: Creates an empty check. Only `name` is required; `language` and `test_type` are optional and default to 13 and 1 respectively.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  example: CS-201 Assignment 4
                  minLength: 3
                  maxLength: 255
                  description: Check name.
                language:
                  type: integer
                  default: 13
                  description: Language id from GET /languages. Use 999 for Auto Detect; an unknown/invalid id falls back to Auto Detect instead of returning an error.
                test_type:
                  type: integer
                  minimum: 1
                  default: 1
                  description: Engine id from GET /test-types.
                ai_run:
                  type: boolean
                  default: true
                  description: Run AI-generated-code detection on this check. Accepts true/false/1/0.
                base_code_detection:
                  type: boolean
                  default: false
                  description: Detect shared base/boilerplate (starter) code.
                callback_url:
                  type: string
                  format: uri
                  example: https://example.edu/hooks/codequiry
                  maxLength: 500
                  description: Webhook destination for this check. Codequiry POSTs a signed JSON payload here when the check completes or fails, so you do not have to poll. Must be a publicly reachable http(s) URL - loopback, private and link-local addresses are rejected with 422. Overrides the account-level webhook URL set in Dashboard -> API Keys. See the Webhooks section of the API description.
      responses:
        '201':
          description: Created check
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckCreated'
        '401':
          $ref: '#/components/responses/InvalidKey'
        '402':
          $ref: '#/components/responses/BillingSuspended'
        '429':
          $ref: '#/components/responses/RateLimited'
        '422':
          $ref: '#/components/responses/ValidationError'
    servers:
    - url: https://codequiry.com/api/v1
      description: Production
  /check/get:
    post:
      tags:
      - Checks
      operationId: getCheck
      summary: Get a check
      description: Returns a check with its status, submission count, and submissions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - check_id
              properties:
                check_id:
                  type: integer
                  example: 12345
                  minimum: 1
      responses:
        '200':
          description: Check detail
          content:
            application/json:
              schema:
                type: object
                properties:
                  check:
                    $ref: '#/components/schemas/Check'
                  status:
                    type: string
                    example: Completed
                  submission_count:
                    type: integer
                    example: 28
                  submissions:
                    type: array
                    items:
                      $ref: '#/components/schemas/Submission'
        '401':
          $ref: '#/components/responses/InvalidKey'
        '402':
          $ref: '#/components/responses/BillingSuspended'
        '429':
          $ref: '#/components/responses/RateLimited'
        '422':
          $ref: '#/components/responses/ValidationError'
    servers:
    - url: https://codequiry.com/api/v1
      description: Production
  /check/update:
    post:
      tags:
      - Checks
      operationId: updateCheckPost
      summary: Update a check
      description: Renames a check and/or changes its language. Equivalent to PATCH /checks/{checkId}.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - check_id
              properties:
                check_id:
                  type: integer
                  example: 12345
                name:
                  type: string
                  example: CS-201 Assignment 4 (regrade)
                  minLength: 3
                  maxLength: 255
                language:
                  type: integer
                  example: 13
                  description: Language id from GET /languages. Use 999 for Auto Detect. As on /check/create, an unknown or invalid id falls back to Auto Detect and still returns 200 - the check is never left pointing at a language that does not exist, but a typo will not be reported either.
      responses:
        '200':
          description: Updated check
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Check updated successfully
                  check:
                    $ref: '#/components/schemas/Check'
        '401':
          $ref: '#/components/responses/InvalidKey'
        '402':
          $ref: '#/components/responses/BillingSuspended'
        '429':
          $ref: '#/components/responses/RateLimited'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
    servers:
    - url: https://codequiry.com/api/v1
      description: Production
  /checks/{checkId}:
    get:
      tags:
      - Checks
      operationId: getCheckRest
      summary: Get a check (REST)
      description: Retrieves a check with its status, submission count, and submissions. Equivalent to POST /check/get.
      parameters:
      - $ref: '#/components/parameters/CheckId'
      responses:
        '200':
          description: Check detail
          content:
            application/json:
              schema:
                type: object
                properties:
                  check:
                    $ref: '#/components/schemas/Check'
                  status:
                    type: string
                    example: Completed
                  submission_count:
                    type: integer
                    example: 28
                  submissions:
                    type: array
                    items:
                      $ref: '#/components/schemas/Submission'
        '401':
          $ref: '#/components/responses/InvalidKey'
        '402':
          $ref: '#/components/responses/BillingSuspended'
        '429':
          $ref: '#/components/responses/RateLimited'
        '422':
          $ref: '#/components/responses/ValidationError'
    patch:
      tags:
      - Checks
      operationId: updateCheck
      summary: Update a check (REST)
      parameters:
      - $ref: '#/components/parameters/CheckId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: CS-201 Assignment 4 (regrade)
                  minLength: 3
                  maxLength: 255
                language:
                  type: integer
                  example: 13
                  description: Language id from GET /languages. Use 999 for Auto Detect. An unknown or invalid id falls back to Auto Detect and still returns 200.
      responses:
        '200':
          description: Updated check
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Check updated successfully
                  check:
                    $ref: '#/components/schemas/Check'
        '401':
          $ref: '#/components/responses/InvalidKey'
        '402':
          $ref: '#/components/responses/BillingSuspended'
        '429':
          $ref: '#/components/responses/RateLimited'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      tags:
      - Checks
      operationId: deleteCheck
      summary: Delete a check (REST)
      parameters:
      - $ref: '#/components/parameters/CheckId'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResult'
        '401':
          $ref: '#/components/responses/InvalidKey'
        '402':
          $ref: '#/components/responses/BillingSuspended'
        '429':
          $ref: '#/components/responses/RateLimited'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
    servers:
    - url: https://codequiry.com/api/v1
      description: Production
  /check/delete:
    post:
      tags:
      - Checks
      operationId: deleteCheckPost
      summary: Delete a check
      description: Equivalent to DELETE /checks/{checkId}. Free-trial and demo checks cannot be deleted (403); a processing check cannot be deleted (409).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - check_id
              properties:
                check_id:
                  type: integer
                  example: 12345
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResult'
        '401':
          $ref: '#/components/responses/InvalidKey'
        '402':
          $ref: '#/components/responses/BillingSuspended'
        '429':
          $ref: '#/components/responses/RateLimited'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
    servers:
    - url: https://codequiry.com/api/v1
      description: Production
components:
  responses:
    Conflict:
      description: Check is in a state that does not allow this operation (e.g. still processing, or not yet completed).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found or not owned by this account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: Request validation failed.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              validation_errors:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: string
    BillingSuspended:
      description: The account is suspended for an unpaid invoice. Every endpoint returns this until the invoice is paid from the billing dashboard; it is not retryable and the request was not performed.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              invoice:
                type: string
                nullable: true
                description: Stripe invoice id of the unpaid invoice.
          example:
            error: Account suspended due to an unpaid invoice. Pay the outstanding invoice from your billing dashboard to restore API access.
            invoice: in_1QxYz...
    InvalidKey:
      description: Missing or invalid API key. The API key is checked before any endpoint logic runs, so this is returned for every operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing:
              summary: No apikey header
              value:
                error: No API Key (apikey) provided in header request
            invalid:
              summary: Unknown or malformed key
              value:
                error: Unauthorized, make sure your API Key is valid an associated with an account. Create an account at codequiry.com
    Forbidden:
      description: Not permitted (e.g. free-trial limitation, or a read-only demo check).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: 'Rate limit exceeded: more than 60 requests in one minute from this IP. Retry after the number of seconds in the Retry-After header. Successful responses carry X-RateLimit-Limit and X-RateLimit-Remaining too, so you can pace a client without waiting to be refused.'
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: Always 60.
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Calls left in the window (0 here).
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Unix timestamp when the window reopens. Sent only on 429.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Submission:
      type: object
      properties:
        id:
          type: integer
          example: 90271
        assignment_id:
          type: integer
          example: 12345
        filename:
          type: string
          example: nowak_alice_a4.zip
        status_id:
          type: integer
          example: 4
        total_result:
          type: number
          example: 75
        result_web:
          type: number
          example: 89
        submissionresults:
          type: array
          description: One row per peer submission this one scored against, highest score first.
          items:
            type: object
            properties:
              id:
                type: integer
                example: 3104428
              submission_id:
                type: integer
                example: 90271
              submission_id_compared:
                type: integer
                example: 90272
              score:
                type: number
                description: Similarity percentage against that submission.
                example: 86
              file:
                type: string
                example: nowak_alice_a4/BankAccount.java
              file_matched:
                type: string
                example: carter_ben_a4/BankAccount.java
              lines:
                type: integer
                description: Lines covered by the matched region.
                example: 90
              longest:
                type: integer
                description: Longest single matched run, in lines.
                example: 60
              location:
                type: string
                description: Empty for peer matches; the path within the source for web matches.
                example: ''
              source:
                type: string
                example: Peer submission
    Check:
      type: object
      description: A check (internally an assignment). Endpoints return the full assignment row, so more fields are present than are listed here; only the stable, documented ones are shown.
      properties:
        stats:
          type: object
          nullable: true
          description: Present only when the list was requested with with_stats=1. Averages and maxima are over finished submissions and are null when there are none.
          properties:
            submissions:
              type: integer
              example: 24
            completed:
              type: integer
              example: 24
            failed:
              type: integer
              example: 0
            avg_group:
              type: number
              nullable: true
              example: 18.4
            max_group:
              type: number
              nullable: true
              example: 82
            avg_web:
              type: number
              nullable: true
              example: 9.1
            max_web:
              type: number
              nullable: true
              example: 100
            flagged:
              type: integer
              example: 2
              description: Finished submissions at or above 75% Group or Web.
            avg_ai:
              type: number
              nullable: true
              example: 31.6
            max_ai:
              type: number
              nullable: true
              example: 97.2
            ai_submissions:
              type: integer
              example: 24
            ai_flagged:
              type: integer
              example: 3
              description: Submissions whose mean AI probability is 75% or more.
            matches:
              type: integer
              example: 41
              description: 'Match total as the dashboard counts it: peer fragments, web sources (one per source) and AI blocks.'
        id:
          type: integer
          example: 12345
        name:
          type: string
          example: CS-201 Assignment 4
        status_id:
          type: integer
          example: 4
        language_id:
          type: integer
          example: 13
        test_type:
          type: integer
          example: 1
        ai_run:
          type: integer
          description: 1 if AI-generated-code detection runs for this check.
          example: 1
        base_code_detection:
          type: integer
          description: 1 if base/boilerplate-code detection is enabled.
          example: 0
        created_at:
          type: string
          example: '2026-08-11 09:14:02'
        updated_at:
          type: string
          example: '2026-08-11 09:41:37'
        assignmentstatuses:
          type: object
          description: Expanded status, included only by GET/POST /checks. Not returned by /check/create, /check/get or /check/update - use status_id there, or the top-level status string that /check/get returns.
          properties:
            id:
              type: integer
              example: 4
            status:
              type: string
              example: Completed
    Error:
      type: object
      properties:
        error:
          type: string
          example: Invalid check_id provided.
    DeleteResult:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Check deleted successfully
        check_id:
          type: integer
          example: 12345
        check_name:
          type: string
          example: CS-201 Assignment 4
    CheckCreated:
      type: object
      description: The check as returned by /check/create. Same row as Check but without the expanded assignmentstatuses relation.
      properties:
        id:
          type: integer
          description: Save this - it is the check_id every other endpoint takes.
          example: 12345
        name:
          type: string
          example: CS-201 Assignment 4
        status_id:
          type: integer
          description: Always 1 (new) on creation.
          example: 1
        language_id:
          type: integer
          example: 13
        test_type:
          type: integer
          example: 1
        ai_run:
          type: integer
          example: 1
        base_code_detection:
          type: integer
          example: 0
        job_id:
          type: integer
          description: 0 until the check is started.
          example: 0
        created_at:
          type: string
          example: '2026-08-11 09:14:02'
        updated_at:
          type: string
          example: '2026-08-11 09:14:02'
  parameters:
    CheckId:
      name: checkId
      in: path
      required: true
      schema:
        type: integer
        example: 12345
      description: The check (assignment) id.
  securitySchemes:
    apikey:
      type: apiKey
      in: header
      name: apikey
      description: Your 64-character API key from the Codequiry dashboard.
x-refined-from:
- codequiry-com-openapi-original.json
- codequiry-com-openapi.yml