API Reference — Carabid

Overview

All API requests are made over HTTPS. The base URL for all endpoints is:

Base URL https://api.carabid.ai

Responses are always JSON. Request bodies must be JSON with Content-Type: application/json.

Authentication

Protected endpoints require an API key. Pass it in one of two ways:

Via header (recommended)

Authorization: Bearer sk_your_api_key

Via query parameter

GET /api/v1/hello?api_key=sk_your_api_key

API keys start with sk_ and are generated on registration. You can create and manage keys from your dashboard.

Rate limit: 100 requests per minute per API key. Exceeding this returns 429 Too Many Requests.

Errors

Errors return a JSON object with an error field describing the problem.

{
  "error": "Invalid API key."
}

Status codes

200Success

201Created

400Bad request — missing or invalid fields

401Unauthorized — missing or invalid credentials

404Not found

409Conflict — e.g. email already registered

429Rate limit exceeded

Auth

POST /auth/register Create a new account

Creates a new user account. Returns an API key automatically — no separate key creation step required.

Body parameters

Name	Type	Required	Description
email	string	required	Valid email address
password	string	required	Min. 8 characters

Example request

curl -X POST https://api.carabid.ai/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"yourpassword"}'

Response 201 Created

{
  "message": "Account created.",
  "api_key": "sk_a1b2c3..."
}

POST /auth/login Obtain a session token

Returns a session token used to manage API keys. Pass it as Authorization: Bearer <token> on key management requests.

Body parameters

Name	Type	Required	Description
email	string	required	Account email
password	string	required	Account password

Example request

curl -X POST https://api.carabid.ai/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"yourpassword"}'

Response 200 OK

{
  "token": "eyJ...",
  "email": "you@example.com"
}

GET /auth/keys List your API keys

Returns all API keys for the authenticated user.

Auth required: Session token from /auth/login

Example request

curl https://api.carabid.ai/auth/keys \
  -H "Authorization: Bearer <session_token>"

Response 200 OK

{
  "keys": [
    {
      "id": 1,
      "name": "default",
      "key": "sk_a1b2c3...",
      "created_at": "2026-03-25 03:00:00",
      "last_used": "2026-03-25 04:00:00"
    }
  ]
}

POST /auth/keys Create a new API key

Creates a new API key for the authenticated user. Maximum 10 keys per account.

Auth required: Session token from /auth/login

Body parameters

Name	Type	Required	Description
name	string	optional	Label for the key. Defaults to `"default"`

Example request

curl -X POST https://api.carabid.ai/auth/keys \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"production"}'

Response 201 Created

{
  "key": "sk_a1b2c3...",
  "name": "production"
}

DELETE /auth/keys/:id Delete an API key

Permanently deletes an API key. Any requests using this key will immediately return 401.

Auth required: Session token from /auth/login

Path parameters

Name	Type	Description
id	integer	Key ID from `GET /auth/keys`

Example request

curl -X DELETE https://api.carabid.ai/auth/keys/1 \
  -H "Authorization: Bearer <session_token>"

Response 200 OK

{ "message": "Key deleted." }

Test

A simple endpoint to verify your API key is working.

GET /api/v1/hello Hello World — verify your API key

Query parameters

Name	Type	Required	Description
arg	string	optional	Value appended to the response message

Example request

curl "https://api.carabid.ai/api/v1/hello?arg=world" \
  -H "Authorization: Bearer sk_your_key"

Response 200 OK

{ "message": "Hello World: world" }

Policies

GET /api/v1/policies List all saved policies

Response

{ "policies": [ { "id": 1, "name": "GDPR", "created_at": "...", "extraction_count": 2, "last_extracted": "..." } ] }

GET /api/v1/policies/:id Get policy text and extraction history

Response

{ "policy": { "id": 1, "name": "...", "text": "..." }, "extractions": [ ... ] }

POST /api/v1/policies Save a new policy

Body

{ "name": "GDPR", "text": "Full policy document text..." }

Response 201 Created

{ "id": 1, "name": "GDPR" }

Example

curl -X POST https://api.carabid.ai/api/v1/policies \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"GDPR","text":"The data subject shall have the right..."}'

PUT /api/v1/policies/:id Update policy name and/or text

Body (all fields optional)

{ "name": "GDPR v2", "text": "Updated policy text..." }

DELETE /api/v1/policies/:id Delete a policy and all its extractions

Response

{ "message": "Policy deleted." }

POST /api/v1/policies/:id/extract Run LTL rule extraction on a saved policy

Body

{ "openai_api_key": "sk-...", "organization": "Acme Corp" }

Response

{ "extraction_id": 5, "organization": "Acme Corp", "circuit_count": 3, "circuits": [ ... ] }

Example

curl -X POST https://api.carabid.ai/api/v1/policies/1/extract \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"openai_api_key":"sk-openai-...","organization":"Acme Corp"}'

GET /api/v1/extractions/:id Retrieve a saved extraction result

Response

{ "id": 5, "organization": "...", "circuit_count": 3, "circuits": [ ... ] }

Data Tagging

POST /api/v1/tag Tag data against predicates from a saved extraction

Body

{ "extraction_id": 5, "data_text": "User foo@example.com requested access to /admin...", "openai_api_key": "sk-..." }

Response

{
  "organization": "Acme Corp",
  "predicate_count": 8,
  "tags": [ { "predicate": "is_authorized_user", "value": false }, ... ],
  "circuit_results": [ { "action": "access_data", "is_safe": false, "violated_rules": ["G(access_data -> is_authorized_user)"], "safety_score": 0.0 }, ... ]
}

Example

curl -X POST https://api.carabid.ai/api/v1/tag \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"extraction_id":5,"data_text":"User accessed admin panel without MFA","openai_api_key":"sk-openai-..."}'

POST /api/v1/verify Verify that a tool call does not violate a policy

Runs the full ShieldAgent pipeline against the policy circuits from a saved extraction. Returns ALLOW or BLOCK along with any violated LTL rules and an explanation.

Body

{
  "extraction_id": 5,
  "tool": "send_email",
  "args": { "to": "ceo@example.com", "body": "Confidential report attached." },
  "goal_summary": "The agent is summarizing Q3 earnings and sending a report to stakeholders.",
  "openai_api_key": "sk-...",
  "prior_actions": [],
  "session_id": "session-abc"
}

Response — ALLOW

{
  "organization": "Acme Corp",
  "tool": "send_email",
  "decision": "ALLOW",
  "explanation": "The action complies with all policy predicates.",
  "violated_rules": [],
  "modified_args": null
}

Response — BLOCK

{
  "organization": "Acme Corp",
  "tool": "send_email",
  "decision": "BLOCK",
  "explanation": "The action violates data exfiltration rules: email recipient is external and content is marked confidential.",
  "violated_rules": ["G(send_email -> is_authorized_recipient)", "F(confidential_data -> !external_recipient)"],
  "modified_args": null
}

Example

curl -X POST https://api.carabid.ai/api/v1/verify \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "extraction_id": 5,
    "tool": "send_email",
    "args": {"to":"external@company.com","body":"Attached: confidential report"},
    "goal_summary": "Agent summarizing and distributing Q3 earnings.",
    "openai_api_key": "sk-openai-..."
  }'