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

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.

Header
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.

Keep it server-side

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.

Note

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.

Shell
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"
Tip

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.

GET /pipelines List the workspace's pipelines
GET /pipelines/{id} One pipeline with criteria, resources, templates and prompts
GET /pipelines/{id}/templates Report templates available for the pipeline
DELETE /pipelines/{id} Remove the pipeline from the workspace

Catalog

GET /catalog Pipeline templates available to add
POST /catalog/{templateId}/add Add a pipeline to the workspace

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

POST /pipelines/{id}/documents/sources Upload source documents
POST /pipelines/{id}/documents/targets Upload target documents
Upload two sources
curl -X POST "$BASE/pipelines/$PIPELINE_ID/documents/sources" \
  -H "Authorization: Bearer $KEY" \
  -F "files=@job-description.pdf" \
  -F "files=@hiring-rubric.docx"
Note

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

GET /pipelines/{id}/documents List the pipeline's documents
GET /pipelines/{id}/documents/{documentId} One document's metadata
GET /pipelines/{id}/documents/{documentId}/download Download the file
DELETE /pipelines/{id}/documents/{documentId} Remove the document from the pipeline

Across the workspace

GET /documents List documents
GET /documents/{id} One document's metadata
GET /documents/{id}/download Download the file
DELETE /documents/{id} Delete the document

Query parameters on GET /documents

ParameterValuesEffect
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.

GET /pipelines/{id}/criteria List criteria sets
GET /pipelines/{id}/criteria/{criteriaId} One criteria set in full
POST /pipelines/{id}/criteria Create a criteria set
PUT /pipelines/{id}/criteria/{criteriaId} Update name, description or criteria items
DELETE /pipelines/{id}/criteria/{criteriaId} Delete the criteria set
POST /pipelines/{id}/criteria/{criteriaId}/generate Generate criteria from the pipeline's source documents
POST /pipelines/{id}/criteria/{criteriaId}/generate/criterion Generate one additional criterion
POST /pipelines/{id}/criteria/{criteriaId}/lock Lock the set against edits
POST /pipelines/{id}/criteria/{criteriaId}/unlock Reopen the set for editing
POST /pipelines/{id}/criteria/{criteriaId}/set-default Make it the pipeline's default set

Query parameters on the list

ParameterValuesEffect
searchstringMatch on criteria set name
status live, draft, paused Filter by derived status
limit1–100Page size
offsetintegerPage offset
Unlocking

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.

GET /pipelines/{id}/criteria/{criteriaId}/comparisons The pairwise comparison matrix
PUT /pipelines/{id}/criteria/{criteriaId}/comparisons Record one comparison
POST /pipelines/{id}/criteria/{criteriaId}/comparisons/generate/simple Derive weights, fast path
POST /pipelines/{id}/criteria/{criteriaId}/comparisons/generate/advanced Derive weights with finer-grained reasoning

Runs

A run evaluates one target against one locked criteria set. Runs move through PENDING → PROCESSING → COMPLETE or FAILED.

POST /runs Create and start a run
GET /runs List runs
GET /runs/{id} One run with criteria, evaluation, decision and summary
GET /runs/{id}/data Raw execution results
GET /runs/{id}/report Rendered report
POST /runs/{id}/retrigger Re-run a failed or completed run
PATCH /runs/{id} Rename the run
DELETE /runs/{id} Delete the run

Creating a run

POST /runs
{
  "pipeline_id": "uuid",
  "criteria_id": "uuid",
  "name": "Candidate A",
  "description": "optional",
  "target": {
    "type": "DOCUMENTS",
    "value": ["document-uuid"]
  },
  "options": {}
}
Target typevalue
DOCUMENTSArray of document IDs
TEXTRaw text
IDAn identifier the pipeline resolves
SLUGA named handle the pipeline resolves

Listing runs

ParameterValuesEffect
status DRAFT, PENDING, PROCESSING, COMPLETE, FAILED Filter by run status
pipeline_idUUIDRuns on one pipeline
run_idUUIDOne specific run
searchstringMatch on run id prefix or run name
days 1d, 7d, 30d, 90d Time window
limit1–100Page size
offsetintegerPage offset

Reports

ParameterValuesEffect
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.
Download a PDF report
curl -s "$BASE/runs/$RUN_ID/report?filetype=pdf" \
  -H "Authorization: Bearer $KEY" \
  -o report.pdf
Polling

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.

GET /runs/{id}/artifacts The run's artifact
ParameterValuesEffect
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.

GET /activity-logs Audit trail entries
GET /usage-logs Usage with token counts and model info

Activity log parameters

ParameterValuesEffect
resource_typestringFilter by resource type
resource_idUUIDEverything that happened to one resource
actionstringFilter by action
actor_idUUIDFilter by who did it
actor_type user, api_key Separate human actions from programmatic ones
days 1d, 7d, 30d, 90d Time window
limit1–100Page size
offsetintegerPage offset

Usage log parameters

ParameterValuesEffect
operationstringFilter by operation type
user_idUUIDFilter by user
days 1d, 7d, 30d, 90d Time window
limit1–100Page size
offsetintegerPage offset

Errors

Errors come back as JSON with a message describing what went wrong.

StatusMeans
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.
500Something failed on our side.
Note

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.