# Codequiry API — Full Reference (for developers and AI agents)

> Source-code plagiarism, peer similarity, web/database matching, and AI-generated-code detection.

Version: 1.0.0  |  Base URL: `https://codequiry.com/api/v1`  |  Machine-readable spec: https://codequiry.com/openapi.json

## Authentication
Every request requires the header `apikey: <YOUR_API_KEY>` (a 64-character key from your Codequiry dashboard). There is no OAuth or Bearer token. Missing/invalid keys return HTTP 401 `{"error":"Invalid API key"}`.

## Typical flow
1. `POST /check/create` — create a check (returns its `id`).
2. `POST /check/upload` (or `/check/upload-batch`) — upload ZIP submission(s) to that check.
3. `POST /check/start` — queue analysis.
4. `POST /check/status` (or `GET /checks/{checkId}/status`) — poll until `status_id` is 4 (completed).
5. `POST /check/overview` then `POST /check/results` — read scores and detailed matches. `GET/POST /ai-results` for AI detection.

Tip: `POST /check/quick` does create+upload+start in one multipart call.

## Status codes (status_id)
1 = New, 6 = Processing, 7 = Queued, 4 = Completed, 3 = Failed.

## Auth

### GET /auth/validate
**Validate API key**
Confirms the supplied `apikey` header is valid and returns the owning account.

Responses:
- `200` — Key is valid → { valid, user_id, email, name } (schema: KeyValidation)
- `401` — Missing or invalid API key.

Example:
```bash
curl -X GET "https://codequiry.com/api/v1/auth/validate" -H "apikey: YOUR_API_KEY"
```

### POST /auth/validate
**Validate API key (POST)**
Identical to the GET form.

Responses:
- `200` — Key is valid → { valid, user_id, email, name } (schema: KeyValidation)
- `401` — Missing or invalid API key.

Example:
```bash
curl -X POST "https://codequiry.com/api/v1/auth/validate" -H "apikey: YOUR_API_KEY"
```

### GET /account
**Get account & quota**
Returns the authenticated user's profile, plan, and remaining check quota.

Responses:
- `200` — Account info → { id, name, email, quota, submissions, is_pro, plan_id, edu_verified } (schema: Account)
- `401` — Missing or invalid API key.

Example:
```bash
curl -X GET "https://codequiry.com/api/v1/account" -H "apikey: YOUR_API_KEY"
```

### POST /account
**Get account & quota (POST)**

Responses:
- `200` — Account info → { id, name, email, quota, submissions, is_pro, plan_id, edu_verified } (schema: Account)
- `401` — Missing or invalid API key.

Example:
```bash
curl -X POST "https://codequiry.com/api/v1/account" -H "apikey: YOUR_API_KEY"
```

## Reference

### GET /languages
**List supported languages**
Languages you may pass to `language` when creating a check. Each entry includes the numeric `id` used by the API.

Responses:
- `200` — Language catalog → { success, count, languages } (schema: LanguageList)
- `401` — Missing or invalid API key.

Example:
```bash
curl -X GET "https://codequiry.com/api/v1/languages" -H "apikey: YOUR_API_KEY"
```

### POST /languages
**List supported languages (POST)**

Responses:
- `200` — Language catalog → { success, count, languages } (schema: LanguageList)
- `401` — Missing or invalid API key.

Example:
```bash
curl -X POST "https://codequiry.com/api/v1/languages" -H "apikey: YOUR_API_KEY"
```

### GET /test-types
**List engines (test types)**
Returns the analysis engines available to your account. Use a returned `id` as `test_type` on create/start/quick. `default_test_type` is 1 and `recommended_test_type` is 9 (Group Similarity). Engine `id`s are live database ids, not a fixed sequence.

Responses:
- `200` — Engine catalog and your access → { success, test_types, user_access, default_test_type, recommended_test_type, note } (schema: TestTypeList)
- `401` — Missing or invalid API key.
- `500` — Unexpected server error.

Example:
```bash
curl -X GET "https://codequiry.com/api/v1/test-types" -H "apikey: YOUR_API_KEY"
```

### POST /test-types
**List engines (test types) (POST)**

Responses:
- `200` — Engine catalog and your access → { success, test_types, user_access, default_test_type, recommended_test_type, note } (schema: TestTypeList)
- `401` — Missing or invalid API key.
- `500` — Unexpected server error.

Example:
```bash
curl -X POST "https://codequiry.com/api/v1/test-types" -H "apikey: YOUR_API_KEY"
```

## Checks

### GET /checks
**List your checks**
Returns every check (assignment) owned by the account, newest first, each with its status object.

Responses:
- `200` — Array of checks → array of { id, name, status_id, language_id, test_type, ai_run, base_code_detection, created_at, updated_at, assignmentstatuses } (schema: Check)
- `401` — Missing or invalid API key.

Example:
```bash
curl -X GET "https://codequiry.com/api/v1/checks" -H "apikey: YOUR_API_KEY"
```

### POST /checks
**List your checks (POST)**

Responses:
- `200` — Array of checks → array of { id, name, status_id, language_id, test_type, ai_run, base_code_detection, created_at, updated_at, assignmentstatuses } (schema: Check)
- `401` — Missing or invalid API key.

Example:
```bash
curl -X POST "https://codequiry.com/api/v1/checks" -H "apikey: YOUR_API_KEY"
```

### POST /check/create
**Create a check**
Creates an empty check. Only `name` is required; `language` and `test_type` are optional and default to 13 and 1 respectively.

Request body (`application/json`):
- `name` (string, required) — Check name.
- `language` (integer, optional, default 13) — Language id from GET /languages.
- `test_type` (integer, optional, default 1) — Engine id from GET /test-types.
- `ai_run` (boolean, optional, default 1) — Run AI-generated-code detection on this check. Accepts true/false/1/0.
- `base_code_detection` (boolean, optional, default ) — Detect shared base/boilerplate (starter) code.

Responses:
- `201` — Created check → { id, name, status_id, language_id, test_type, ai_run, base_code_detection, created_at, updated_at, assignmentstatuses } (schema: Check)
- `401` — Missing or invalid API key.
- `422` — Request validation failed.

Example:
```bash
curl -X POST "https://codequiry.com/api/v1/check/create" -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" -d '{ ... }'
```

### POST /check/get
**Get a check**
Returns a check with its status, submission count, and submissions.

Request body (`application/json`):
- `check_id` (integer, required) — 

Responses:
- `200` — Check detail → { check, status, submission_count, submissions }
- `401` — Missing or invalid API key.
- `422` — Request validation failed.

Example:
```bash
curl -X POST "https://codequiry.com/api/v1/check/get" -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" -d '{ ... }'
```

### POST /check/update
**Update a check**
Renames a check and/or changes its language. Equivalent to PATCH /checks/{checkId}.

Request body (`application/json`):
- `check_id` (integer, required) — 
- `name` (string, optional) — 
- `language` (integer, optional) — 

Responses:
- `200` — Updated check → { success, message, check }
- `401` — Missing or invalid API key.
- `403` — Not permitted (e.g. free-trial limitation, or a read-only demo check).
- `404` — Resource not found or not owned by this account.
- `422` — Request validation failed.

Example:
```bash
curl -X POST "https://codequiry.com/api/v1/check/update" -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" -d '{ ... }'
```

### GET /checks/{checkId}
**Get a check (REST)**
Retrieves a check with its status, submission count, and submissions. Equivalent to POST /check/get.

Parameters:
- `checkId` (path, integer, required) — The check (assignment) id.

Responses:
- `200` — Check detail → { check, status, submission_count, submissions }
- `401` — Missing or invalid API key.
- `422` — Request validation failed.

Example:
```bash
curl -X GET "https://codequiry.com/api/v1/checks/{checkId}" -H "apikey: YOUR_API_KEY"
```

### PATCH /checks/{checkId}
**Update a check (REST)**

Parameters:
- `checkId` (path, integer, required) — The check (assignment) id.

Request body (`application/json`):
- `name` (string, optional) — 
- `language` (integer, optional) — 

Responses:
- `200` — Updated check → { success, message, check }
- `401` — Missing or invalid API key.
- `403` — Not permitted (e.g. free-trial limitation, or a read-only demo check).
- `404` — Resource not found or not owned by this account.
- `422` — Request validation failed.

Example:
```bash
curl -X PATCH "https://codequiry.com/api/v1/checks/{checkId}" -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" -d '{ ... }'
```

### DELETE /checks/{checkId}
**Delete a check (REST)**

Parameters:
- `checkId` (path, integer, required) — The check (assignment) id.

Responses:
- `200` — Deleted → { success, message, check_id, check_name } (schema: DeleteResult)
- `401` — Missing or invalid API key.
- `403` — Not permitted (e.g. free-trial limitation, or a read-only demo check).
- `404` — Resource not found or not owned by this account.
- `409` — Check is in a state that does not allow this operation (e.g. still processing, or not yet completed).

Example:
```bash
curl -X DELETE "https://codequiry.com/api/v1/checks/{checkId}" -H "apikey: YOUR_API_KEY"
```

### POST /check/delete
**Delete a check**
Equivalent to DELETE /checks/{checkId}. Free-trial and demo checks cannot be deleted (403); a processing check cannot be deleted (409).

Request body (`application/json`):
- `check_id` (integer, required) — 

Responses:
- `200` — Deleted → { success, message, check_id, check_name } (schema: DeleteResult)
- `401` — Missing or invalid API key.
- `403` — Not permitted (e.g. free-trial limitation, or a read-only demo check).
- `404` — Resource not found or not owned by this account.
- `409` — Check is in a state that does not allow this operation (e.g. still processing, or not yet completed).
- `422` — Request validation failed.

Example:
```bash
curl -X POST "https://codequiry.com/api/v1/check/delete" -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" -d '{ ... }'
```

## Submissions

### POST /check/upload
**Upload a submission (ZIP)**
Uploads one ZIP archive of source code into a check. Max 10 MB. Call once per submission, or use /check/upload-batch.

Request body (`multipart/form-data`):
- `check_id` (integer, required) — Target check id.
- `file` (string, required) — ZIP archive (mimes:zip, max 10 MB).

Responses:
- `200` — Upload accepted → { data, file, file_size, submission_count, check } (schema: UploadResult)
- `401` — Missing or invalid API key.
- `403` — Not permitted (e.g. free-trial limitation, or a read-only demo check).
- `422` — Request validation failed.
- `500` — Unexpected server error.

Example:
```bash
curl -X POST "https://codequiry.com/api/v1/check/upload" -H "apikey: YOUR_API_KEY" -F "check_id=123" -F "file=@submission.zip"
```

### POST /check/upload-batch
**Upload many submissions**
Uploads 1–50 ZIP files into a check in one request. Per-file failures are reported in `failed_uploads` with a 200 response.

Request body (`multipart/form-data`):
- `check_id` (integer, required) — 
- `files` (array, required) — 1–50 ZIP archives (each mimes:zip, max 10 MB).

Responses:
- `200` — Batch processed → { success, message, uploaded, uploaded_count, failed_count, failed_uploads, check } (schema: BatchUploadResult)
- `401` — Missing or invalid API key.
- `403` — Not permitted (e.g. free-trial limitation, or a read-only demo check).
- `422` — Request validation failed.
- `500` — Unexpected server error.

Example:
```bash
curl -X POST "https://codequiry.com/api/v1/check/upload-batch" -H "apikey: YOUR_API_KEY" -F "check_id=123" -F "file=@submission.zip"
```

### POST /check/deleteSubmission
**Delete a submission**
Removes one submission from a check. Not available on free trials (403) or demo checks (403).

Request body (`application/json`):
- `check_id` (integer, required) — 
- `submission_id` (integer, required) — 

Responses:
- `200` — Deleted → { success, message }
- `401` — Missing or invalid API key.
- `403` — Not permitted (e.g. free-trial limitation, or a read-only demo check).
- `422` — Request validation failed.
- `500` — Unexpected server error.

Example:
```bash
curl -X POST "https://codequiry.com/api/v1/check/deleteSubmission" -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" -d '{ ... }'
```

## Run

### POST /check/start
**Start a check**
Queues analysis for a check that already has submissions. `webcheck` and `dbcheck` only take effect when BOTH are supplied (both true → engine 1, both false → engine 9); otherwise the check's existing engine is used. The check is set to status_id 7 (queued).

Request body (`application/json`):
- `check_id` (integer, required) — 
- `webcheck` (boolean, optional) — Enable internet/web matching.
- `dbcheck` (boolean, optional) — Enable Codequiry database matching.
- `test_type` (integer, optional) — Approved engine id (overrides webcheck/dbcheck mapping).
- `ai_run` (boolean, optional, default 1) — Run AI-generated-code detection on this check. Accepts true/false/1/0.
- `base_code_detection` (boolean, optional, default ) — Detect shared base/boilerplate (starter) code.

Responses:
- `200` — Check queued → { success, check, status, submission_count, checkURL }
- `401` — Missing or invalid API key.
- `403` — Not permitted (e.g. free-trial limitation, or a read-only demo check).
- `409` — Check is in a state that does not allow this operation (e.g. still processing, or not yet completed).
- `422` — Request validation failed.
- `503` — Analysis services are temporarily offline. → { error } (schema: Error)

Example:
```bash
curl -X POST "https://codequiry.com/api/v1/check/start" -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" -d '{ ... }'
```

### POST /check/quick
**Quick check (all-in-one)**
Creates a check, uploads files, and starts analysis in a single authenticated call. Distinct from the public website Quick Check widget.

Request body (`multipart/form-data`):
- `name` (string, required) — 
- `language` (integer, optional, default 13) — 
- `files` (array, required) — One or more ZIP archives (each mimes:zip, max 10 MB).
- `webcheck` (boolean, optional) — 
- `dbcheck` (boolean, optional) — 
- `test_type` (integer, optional) — 
- `ai_run` (boolean, optional, default 1) — Run AI-generated-code detection on this check. Accepts true/false/1/0.
- `base_code_detection` (boolean, optional, default ) — Detect shared base/boilerplate (starter) code.

Responses:
- `201` — Created and started → { success, message, data, next_steps } (schema: QuickCheckResult)
- `401` — Missing or invalid API key.
- `422` — Request validation failed.
- `500` — Unexpected server error.
- `503` — Analysis services are temporarily offline. → { error } (schema: Error)

Example:
```bash
curl -X POST "https://codequiry.com/api/v1/check/quick" -H "apikey: YOUR_API_KEY" -F "check_id=123" -F "file=@submission.zip"
```

### POST /check/status
**Get check status**
Polling endpoint. Equivalent to GET /checks/{checkId}/status.

Request body (`application/json`):
- `check_id` (integer, required) — 

Responses:
- `200` — Status → { check_id, status_id, status, status_message, progress, submissions_total, submissions_completed, estimated_completion } (schema: CheckStatus)
- `401` — Missing or invalid API key.
- `404` — Resource not found or not owned by this account.
- `422` — Request validation failed.

Example:
```bash
curl -X POST "https://codequiry.com/api/v1/check/status" -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" -d '{ ... }'
```

### GET /checks/{checkId}/status
**Get check status (REST)**

Parameters:
- `checkId` (path, integer, required) — The check (assignment) id.

Responses:
- `200` — Status → { check_id, status_id, status, status_message, progress, submissions_total, submissions_completed, estimated_completion } (schema: CheckStatus)
- `401` — Missing or invalid API key.
- `404` — Resource not found or not owned by this account.
- `422` — Request validation failed.

Example:
```bash
curl -X GET "https://codequiry.com/api/v1/checks/{checkId}/status" -H "apikey: YOUR_API_KEY"
```

## Results

### POST /check/overview
**Get results overview**
Per-submission similarity scores and bar-chart data. The check must be completed (status_id 4) or you get 409.

Request body (`application/json`):
- `check_id` (integer, required) — 

Responses:
- `200` — Overview → { overviewURL, submissions, bardata }
- `401` — Missing or invalid API key.
- `409` — Check is in a state that does not allow this operation (e.g. still processing, or not yet completed).
- `422` — Request validation failed.

Example:
```bash
curl -X POST "https://codequiry.com/api/v1/check/overview" -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" -d '{ ... }'
```

### POST /check/overviewCSV
**Get overview as CSV**
Streams a CSV download with columns Submission,Score. Requires a completed check.

Request body (`application/json`):
- `check_id` (integer, required) — 

Responses:
- `200` — CSV file → string
- `401` — Missing or invalid API key.
- `409` — Check is in a state that does not allow this operation (e.g. still processing, or not yet completed).
- `422` — Request validation failed.

Example:
```bash
curl -X POST "https://codequiry.com/api/v1/check/overviewCSV" -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" -d '{ ... }'
```

### POST /check/results
**Get detailed results**
Full match detail for one submission, including peer, web/external, and AI matches.

Request body (`application/json`):
- `check_id` (integer, required) — 
- `submission_id` (integer, required) — 

Responses:
- `200` — Detailed results → { submission, avg, max, min, other_matches, related_submissions, related_files }
- `401` — Missing or invalid API key.
- `409` — Check is in a state that does not allow this operation (e.g. still processing, or not yet completed).
- `422` — Request validation failed.

Example:
```bash
curl -X POST "https://codequiry.com/api/v1/check/results" -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" -d '{ ... }'
```

### POST /check/getRemoteFile
**Get a matched web file**
Fetches the stored content of an external/web match. `location` and `source` come verbatim from a match object in /check/results.

Request body (`application/json`):
- `location` (string, required) — 
- `source` (string, required) — 

Responses:
- `200` — Stored web file → { file }
- `401` — Missing or invalid API key.
- `403` — Not permitted (e.g. free-trial limitation, or a read-only demo check).
- `404` — Resource not found or not owned by this account.
- `422` — Request validation failed.

Example:
```bash
curl -X POST "https://codequiry.com/api/v1/check/getRemoteFile" -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" -d '{ ... }'
```

### GET /ai-results
**Get AI detection results**
AI-generated-code detection and code-quality analysis for every submission in a check.

Parameters:
- `assignment_id` (query, integer, required) — Check id.

Responses:
- `200` — AI results → { success, assignment_status, statistics, submissions } (schema: AIResults)
- `401` — Missing or invalid API key.
- `404` — Resource not found or not owned by this account.
- `422` — Request validation failed.

Example:
```bash
curl -X GET "https://codequiry.com/api/v1/ai-results" -H "apikey: YOUR_API_KEY"
```

### POST /ai-results
**Get AI detection results (POST)**

Request body (`application/json`):
- `assignment_id` (integer, required) — 

Responses:
- `200` — AI results → { success, assignment_status, statistics, submissions } (schema: AIResults)
- `401` — Missing or invalid API key.
- `404` — Resource not found or not owned by this account.
- `422` — Request validation failed.

Example:
```bash
curl -X POST "https://codequiry.com/api/v1/ai-results" -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" -d '{ ... }'
```

### POST /check/summary
**Get check summary**
Aggregate stats for a check. Equivalent to GET /checks/{checkId}/summary.

Request body (`application/json`):
- `check_id` (integer, required) — 

Responses:
- `200` — Summary → { check_id, check_name, status, status_id, submission_count, completed_submissions, plagiarism_stats, ai_detection_stats, flagged_submissions, processing_time_seconds, created_at, updated_at } (schema: CheckSummary)
- `401` — Missing or invalid API key.
- `404` — Resource not found or not owned by this account.
- `422` — Request validation failed.

Example:
```bash
curl -X POST "https://codequiry.com/api/v1/check/summary" -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" -d '{ ... }'
```

### GET /checks/{checkId}/summary
**Get check summary (REST)**

Parameters:
- `checkId` (path, integer, required) — The check (assignment) id.

Responses:
- `200` — Summary → { check_id, check_name, status, status_id, submission_count, completed_submissions, plagiarism_stats, ai_detection_stats, flagged_submissions, processing_time_seconds, created_at, updated_at } (schema: CheckSummary)
- `401` — Missing or invalid API key.
- `404` — Resource not found or not owned by this account.
- `422` — Request validation failed.

Example:
```bash
curl -X GET "https://codequiry.com/api/v1/checks/{checkId}/summary" -H "apikey: YOUR_API_KEY"
```

### POST /check/export
**Export results**
Exports a completed check as JSON or CSV (`format`, default csv). Equivalent to GET /checks/{checkId}/export.

Request body (`application/json`):
- `check_id` (integer, required) — 
- `format` (string, optional, default csv) — 

Responses:
- `200` — Export (JSON body or CSV download) → { check_id, check_name, export_date, submissions } (schema: ExportResult)
- `401` — Missing or invalid API key.
- `404` — Resource not found or not owned by this account.
- `409` — Check is in a state that does not allow this operation (e.g. still processing, or not yet completed).
- `422` — Request validation failed.

Example:
```bash
curl -X POST "https://codequiry.com/api/v1/check/export" -H "apikey: YOUR_API_KEY" -H "Content-Type: application/json" -d '{ ... }'
```

### GET /checks/{checkId}/export
**Export results (REST)**

Parameters:
- `checkId` (path, integer, required) — The check (assignment) id.
- `format` (query, string, optional) — 

Responses:
- `200` — Export (JSON body or CSV download) → { check_id, check_name, export_date, submissions } (schema: ExportResult)
- `401` — Missing or invalid API key.
- `404` — Resource not found or not owned by this account.
- `409` — Check is in a state that does not allow this operation (e.g. still processing, or not yet completed).
- `422` — Request validation failed.

Example:
```bash
curl -X GET "https://codequiry.com/api/v1/checks/{checkId}/export" -H "apikey: YOUR_API_KEY"
```

---
Generated from public/openapi.json by scripts/build-api-docs.php. Do not edit by hand.