Criba for AI agents

Criba's screening pipeline is callable. Give your assistant a tenant-scoped API key and it can open a role, add candidates, invite them and read the results — over plain REST or through the Criba MCP server.

Three ways in

Everything on this page runs on the same credential: a tenant-scoped API key sent in the x-api-key header. Point your agent at the REST API directly, hand it the OpenAPI document so it can describe the surface to itself, or connect it to the hosted MCP server and let it call named tools. There is no separate agent plan and no sandbox tenant — an agent sees exactly the data of the organisation whose key it holds.

What an agent can do

This list is generated from the endpoints Criba publishes in its agent manifest, so it is what the API actually exposes rather than a roadmap. A test fails the build if the manifest and this list stop agreeing.

Read

List candidates across the organisation, paginated
GET /api/v1/candidates
Read one candidate's record
GET /api/v1/candidates/{id}
Read the organisation's remaining interview credits
GET /api/v1/credits/balancecriba_credit_balance
Read a completed interview: signal scores, summary and red flags
GET /api/v1/interviews/{id}criba_get_interview
List the screenings (job openings) in your organisation
GET /api/v1/screeningscriba_list_screenings
Read screening analytics over a date range
GET /api/v1/screenings/analytics
Read headline screening counts for the organisation
GET /api/v1/screenings/dashboard-stats
Read one screening, including the signals it scores against
GET /api/v1/screenings/{id}criba_get_screening
Read a screening's pipeline: who is at which stage
GET /api/v1/screenings/{id}/pipelinecriba_get_pipeline
List a screening's resume submissions that are waiting on an approve-or-reject decision
GET /api/v1/screenings/{id}/resume-reviews

Write

Add a candidate to an existing screening (records only, sends nothing)
POST /api/v1/candidatescriba_add_candidate
Record the advance-or-reject decision on a completed interview
PATCH /api/v1/interviews/{id}/decision
Invite a candidate by email, which sends the invitation and returns a single-use interview link
POST /api/v1/invitationscriba_invite_candidate
Apply one resume decision to many submissions at once, emailing each candidate
PATCH /api/v1/resume-reviews/batch-decision
Approve or reject one resume submission, which emails the candidate
PATCH /api/v1/resume-submissions/{id}/decision
Create a screening with a title and 1 to 5 signals
POST /api/v1/screeningscriba_create_screening
Move a screening through draft, open, closed, cancelled or archived
PATCH /api/v1/screenings/{id}/status

Endpoints marked with an MCP tool name are also reachable as a named tool from the MCP server.

Get an API key

Keys are minted by an admin from inside the product and are scoped to one organisation. The plaintext key is shown exactly once, at creation — Criba stores only its hash and cannot show or resend it later. Revoke a key from the same screen and every agent holding it stops working immediately.

Sign in as an admin
Only the admin role can create or revoke API keys. Members can use a key an admin gave them, but cannot mint one.
Open Settings and the API Keys tab
Give the key a name you will recognise later — the agent or machine that will hold it — and copy it before closing the dialog.
Store it as a secret
Send it as the x-api-key header on every request. Treat it like a password: it carries the permissions of the role it was created with, for your whole organisation.

Open Settings → API Keys

OpenAPI document

Criba serves its full OpenAPI 3 document as JSON, so an agent can read the request and response shapes rather than guess them:

https://api.criba.tech/api/v1/openapi.json

The document itself requires an API key — it is not public. Fetch it with your key in the x-api-key header:

curl -H "x-api-key: $CRIBA_API_KEY" https://api.criba.tech/api/v1/openapi.json

Agent gateways that expect a capability manifest instead of a full schema can read the shorter endpoint catalogue Criba publishes alongside it.

https://api.criba.tech/api/.manifest

MCP server

Criba hosts its MCP server for you, so the hosted endpoint has nothing to install or build. Point any MCP client that supports the Streamable HTTP transport, such as Claude Code or Cursor, at the URL below with the same API key. It exposes the endpoints above as the same named tools, so your agent can call them without you writing any HTTP code.

Server URL

https://api.criba.tech/api/v1/mcp

Add it to your MCP client configuration

{
  "mcpServers": {
    "criba": {
      "url": "https://api.criba.tech/api/v1/mcp",
      "headers": {
        "x-api-key": "<your-criba-api-key>"
      }
    }
  }
}

Replace <your-criba-api-key> with the key you created above. The key is the only credential: it decides which organisation the tools act on and what role they act as.

Or add it to Claude Code in one command

claude mcp add --transport http criba https://api.criba.tech/api/v1/mcp --header "x-api-key: <your-criba-api-key>"

If your client can only send a bearer token, Authorization: Bearer <your-criba-api-key> works too. Other bearer tokens, such as a login session, are rejected.

The same tools also ship as a standalone process that speaks MCP over stdio — the criba-mcp binary — for clients that can only launch local servers. It reads CRIBA_BASE_URL and CRIBA_API_KEY from its environment and uses the same API key, so the tools, redaction and invite confirmation are identical.

Limits worth knowing before you wire it up

Keys are scoped to one organisation
A key carries its own tenant. There is no request shape that reaches another organisation's data, and the tenant is never taken from input.
API-key auth, not OAuth
Authentication is a single shared secret in the x-api-key header. Keys can be given an expiry at creation and can be revoked at any time; a revoked key stops working on the next request.
Rate limited per key
API-key traffic is metered at 600 requests per 60 seconds, bucketed per key rather than per IP — so a runaway integration is contained to its own key, and revoking that key stops it.
Reads are safe, writes are not dry runs
Every GET above only reads. The write calls change your pipeline, and three of them send real email to candidates: inviting a candidate, and approving or rejecting a resume submission (individually or in a batch).
MCP masks candidate PII by default
Through the MCP server every candidate-bearing response is redacted before the agent sees it: emails become ***@domain, a full name keeps the given name and reduces the rest to initials, and phone and location are dropped. Pass includeContactDetails: true on a single call to opt out.
MCP will not email a candidate without confirmation
The invite tool refuses to send until you pass confirm: true. Without it, no HTTP request is made at all and the tool instead describes exactly what it would send.
Some of the product is deliberately out of reach
Resume file upload, the live voice interview, the event stream, billing and all platform-admin routes are not on the agent surface and cannot be reached with an API key.