Developers
API reference
Everything needed to drive the evaluation loop from your own systems: upload sources, build and lock criteria, run evaluations, and pull the record back out. Workspace administration — billing, team, settings — is done in the app and is not covered here.
Base URL
https://dashboard.reckn.app/api
Every path below is relative to that base. Requests and responses are
JSON, except document uploads (multipart/form-data) and PDF
report downloads.
Authentication
Authenticate with a workspace API key as a bearer token. Keys are
rk_-prefixed and are created in the app under Settings →
API keys. Creating and revoking keys requires an admin.
Authorization: Bearer rk_your_api_key
Every call is scoped to the key's workspace. There is no cross-workspace access and no workspace parameter to pass — the key decides. A key acts with operator access: it can run the full evaluation loop, and cannot perform admin-only actions such as managing team members or other keys.
An API key carries access to every evaluation in the workspace. Never ship one in a browser bundle, a mobile app, or anything a customer can read.
Every call made with a key is attributed to that key in the activity log. Use separate keys per integration so the audit trail says which system did what.
End-to-end quickstart
The shortest path from a source document to a result.
BASE=https://dashboard.reckn.app/api
KEY=rk_your_api_key
# 1. Find the pipeline
curl -s "$BASE/pipelines" -H "Authorization: Bearer $KEY"
# 2. Upload the source document criteria come from
curl -s -X POST "$BASE/pipelines/$PIPELINE_ID/documents/sources" \
-H "Authorization: Bearer $KEY" \
-F "files=@job-description.pdf"
# 3. Create a criteria set
curl -s -X POST "$BASE/pipelines/$PIPELINE_ID/criteria" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Senior Platform Engineer"}'
# 4. Generate criteria from the uploaded sources
curl -s -X POST "$BASE/pipelines/$PIPELINE_ID/criteria/$CRITERIA_ID/generate" \
-H "Authorization: Bearer $KEY"
# 5. Derive weights
curl -s -X POST \
"$BASE/pipelines/$PIPELINE_ID/criteria/$CRITERIA_ID/comparisons/generate/simple" \
-H "Authorization: Bearer $KEY"
# 6. Lock the set — required before it can be run against
curl -s -X POST "$BASE/pipelines/$PIPELINE_ID/criteria/$CRITERIA_ID/lock" \
-H "Authorization: Bearer $KEY"
# 7. Upload the target being evaluated
curl -s -X POST "$BASE/pipelines/$PIPELINE_ID/documents/targets" \
-H "Authorization: Bearer $KEY" \
-F "files=@candidate.pdf"
# 8. Run it
curl -s -X POST "$BASE/runs" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d "{
\"pipeline_id\": \"$PIPELINE_ID\",
\"criteria_id\": \"$CRITERIA_ID\",
\"name\": \"Candidate A\",
\"target\": { \"type\": \"DOCUMENTS\", \"value\": [\"$DOCUMENT_ID\"] }
}"
# 9. Read the result
curl -s "$BASE/runs/$RUN_ID" -H "Authorization: Bearer $KEY"
Steps 1–6 happen once per role, RFP or policy. Step 7–9 repeat for every target. Reuse the locked criteria set — that reuse is what makes a batch of results comparable.
Pipelines
A pipeline is the configured evaluation workflow. Pipelines are added to a workspace from the catalog rather than created through the API.
Catalog
Documents
Source documents are what criteria are extracted from.
Target documents are what gets evaluated. Uploads are
multipart/form-data on the files field, up to
10 files per request and 50 MB per file.
Supported types: .pdf, .docx,
.doc, .txt, .rtf,
.xlsx, .csv.
Upload
curl -X POST "$BASE/pipelines/$PIPELINE_ID/documents/sources" \
-H "Authorization: Bearer $KEY" \
-F "files=@job-description.pdf" \
-F "files=@hiring-rubric.docx"
A multi-file upload reports per-file results. Check each entry — one unreadable file does not fail the batch, so a 200 does not mean every file landed.
Within a pipeline
Across the workspace
Query parameters on GET /documents
| Parameter | Values | Effect |
|---|---|---|
pipelineId |
UUID | Only documents on that pipeline |
type |
source, target |
Only documents of that type |
days |
1d, 7d, 30d, 90d |
Only documents created inside that window |
Criteria
A criteria set belongs to a pipeline. It is editable until locked, and a run requires a locked set.
Query parameters on the list
| Parameter | Values | Effect |
|---|---|---|
search | string | Match on criteria set name |
status |
live, draft, paused |
Filter by derived status |
limit | 1–100 | Page size |
offset | integer | Page offset |
Unlocking a set changes what future runs are measured against. Runs already completed keep the version they were evaluated on — but a batch that straddles an unlock is no longer internally comparable. Create a new set instead when the requirements genuinely changed.
Weighting
Weights are derived from pairwise comparisons between criteria. Generate a full set, then override individual comparisons if you disagree.
Runs
A run evaluates one target against one locked criteria set. Runs move
through PENDING → PROCESSING →
COMPLETE or FAILED.
Creating a run
{
"pipeline_id": "uuid",
"criteria_id": "uuid",
"name": "Candidate A",
"description": "optional",
"target": {
"type": "DOCUMENTS",
"value": ["document-uuid"]
},
"options": {}
}
| Target type | value |
|---|---|
DOCUMENTS | Array of document IDs |
TEXT | Raw text |
ID | An identifier the pipeline resolves |
SLUG | A named handle the pipeline resolves |
Listing runs
| Parameter | Values | Effect |
|---|---|---|
status |
DRAFT, PENDING, PROCESSING, COMPLETE, FAILED |
Filter by run status |
pipeline_id | UUID | Runs on one pipeline |
run_id | UUID | One specific run |
search | string | Match on run id prefix or run name |
days |
1d, 7d, 30d, 90d |
Time window |
limit | 1–100 | Page size |
offset | integer | Page offset |
Reports
| Parameter | Values | Effect |
|---|---|---|
filetype |
html, pdf |
Report format. Defaults to HTML; PDF returns binary. |
template |
Template ID |
Which report template to render. IDs come from
GET /pipelines/{id}/templates.
|
curl -s "$BASE/runs/$RUN_ID/report?filetype=pdf" \
-H "Authorization: Bearer $KEY" \
-o report.pdf
POST /runs returns as soon as the run is accepted, not
when it finishes. Poll GET /runs/{id} until the status
leaves PROCESSING before fetching a report.
Artifacts
An artifact is the hashed, versioned record of a run's inputs and outputs. It is what lets you prove, later, that a result is the one that was produced at the time.
| Parameter | Values | Effect |
|---|---|---|
version |
Integer, or all |
A specific version, or every version as summaries. Omitted returns the latest. |
Logs
Two separate records. The activity log is the decision audit trail — who did what, to which resource, when. The usage log is consumption.
Activity log parameters
| Parameter | Values | Effect |
|---|---|---|
resource_type | string | Filter by resource type |
resource_id | UUID | Everything that happened to one resource |
action | string | Filter by action |
actor_id | UUID | Filter by who did it |
actor_type |
user, api_key |
Separate human actions from programmatic ones |
days |
1d, 7d, 30d, 90d |
Time window |
limit | 1–100 | Page size |
offset | integer | Page offset |
Usage log parameters
| Parameter | Values | Effect |
|---|---|---|
operation | string | Filter by operation type |
user_id | UUID | Filter by user |
days |
1d, 7d, 30d, 90d |
Time window |
limit | 1–100 | Page size |
offset | integer | Page offset |
Errors
Errors come back as JSON with a message describing what went wrong.
| Status | Means |
|---|---|
400 |
The request was malformed, or failed validation. The message names the field. |
401 |
Missing, malformed or revoked API key. |
403 |
The key is valid but not permitted — usually an admin-only action attempted with an API key. |
404 |
No such resource in this workspace. A resource that belongs to another workspace is a 404, not a 403. |
500 | Something failed on our side. |
Deleted resources are soft-deleted. A deleted run, document or criteria set returns 404 and disappears from lists, but the audit trail of what happened to it remains.
Login
Request a demo