API reference | CydraLabs

Basics

API basics

Base URL	`https://app.cydralabs.com/api/v1`
Format	JSON requests and responses (UTF-8). Times are ISO 8601 in UTC; IDs are UUIDs.
OpenAPI document	/api/v1/openapi.json (opens in new tab) (OpenAPI 3.1). Each operation's `x-cydra-auth` extension states who may call it.
Interactive explorer	Swagger UI (opens in new tab)
Health	`GET /healthz` (process) and `GET /readyz` (database round trip), outside `/api/v1`.

Authentication

Each endpoint accepts exactly one kind of caller. The reference marks each one:

Caller types
Marker	Caller	How to authenticate
…	A person	Session cookie from OIDC sign-in, plus X-CSRF-Token (the CSRF cookie's value) on POST, PATCH, PUT and DELETE. The permission shown must be granted through your roles.
agent token	An agent	Authorization: Bearer <workload token>. Accepted by the gateway endpoints and nowhere else.
client credentials	An agent	client_id and client_secret of a workload identity, exchanged for a token.
onboarding	A new identity	The short-lived onboarding cookie set when a new person signs in before creating an organisation, or a session.
public	Anyone	No authentication; rate-limited.

Agent workload tokens

POST /api/v1/identities/token
{"grant_type": "client_credentials", "client_id": "cyd_…", "client_secret": "…"}

→ {"access_token": "<JWT>", "token_type": "Bearer", "expires_in": 300, "agent_uri": "agent://acme/sales-agent"}

Tokens are Ed25519-signed JWTs for the audience cydra-gateway, valid for five minutes, and may be reused until they expire. Suspending the agent or revoking its sessions invalidates tokens issued earlier. Workload identities are issued by an administrator and the secret is shown once; see the quick start.

People

People sign in through the portal (OpenID Connect with mandatory multi-factor authentication); sessions are meant for the portal. For automation, register an agent and give it a workload identity. A missing permission returns 403 forbidden with details.required_permission, and the denial is audited. GET /api/v1/auth/me lists your roles and effective permissions.

Errors

{"error": {"code": "validation_failed", "message": "Request validation failed", "correlation_id": "3f0c…", "details": [...]}}

Error codes
HTTP	Typical codes
400	`bad_request`
401	`unauthenticated`, `token_expired`, `invalid_token`, `invalid_audience`, `session_revoked`, `identity_revoked`, `invalid_client`
403	`forbidden`, `csrf_failed`, `module_not_in_plan`, `four_eyes_required`, `self_approval_prohibited`
404	`not_found` (also for other organisations' objects, never 403)
409	`conflict`, `version_conflict`, `idempotency_conflict`, `approval_not_pending`, `approval_expired`, `duplicate_approver`
422	`validation_failed` (with `details`), `confirmation_required`, `invalid_policy`, `invalid_cursor`, `production_requirements`
428	`precondition_required`: `If-Match` is missing
429	`rate_limited`, with `Retry-After`
500	`internal_error`: no internal detail is returned; quote the correlation ID

Conventions

API conventions
Topic	Behaviour
Correlation	Send `X-Correlation-ID` (8–100 of `[A-Za-z0-9._-]`) or one is generated. It is echoed in responses and recorded in logs, audit events and evidence.
Pagination	`?limit=&cursor=` → `{"items": [...], "next_cursor": "…" \| null}`. `limit` is 1–200 (default 50); cursors are opaque.
Idempotency	Action submissions require `Idempotency-Key` (8–200 of `[A-Za-z0-9._:-]`). The same key and body return the original result with `replayed: true`; a different body returns 409.
Concurrency	Records carry `version`. Policy versions, publishing and status changes require `If-Match`; agent updates honour it when sent.
Confirmation	Containment and other high-impact operations take `{"reason": "…", "confirm": true}`.
Rate limits	600 requests a minute per signed-in user; 120 a minute per agent on gateway endpoints; 30 a minute per IP for sign-in and per client for token exchange.

Endpoint reference

Paths are relative to https://app.cydralabs.com. Expand an endpoint for its parameters, request fields and responses. Schema names (for example AgentOut) are defined in the OpenAPI document. Internal endpoints are not part of the public API and are not listed.

Authentication and accounts

Sign-in, sessions, sign-up and organisation onboarding.

GET/api/v1/auth/callbackOIDC redirect URIpublic
Parameters
Name Type Required Notes
code (query) string | null no
state (query) string | null no
error (query) string | null no
Responses
200 Successful Response422 Validation Error
POST/api/v1/auth/dev-loginDevelopment sign-in (disabled in production)public
Request body DevLoginIn
Name Type Required Notes
email string (email) yes
tenant_id string (uuid) | null no
Responses
200 Successful Response422 Validation Error
GET/api/v1/auth/loginStart OIDC sign-in (authorisation code + PKCE)public
Parameters
Name Type Required Notes
return_to (query) string | null no
signup (query) boolean no default false
Responses
200 Successful Response422 Validation Error
POST/api/v1/auth/logoutSign out and revoke the sessionsigned in
Responses
204 Successful Response
POST/api/v1/auth/logout-allSign out of all devicessigned in
Responses
204 Successful Response
GET/api/v1/auth/meCurrent user, organisation, roles and permissionssigned in
Responses
200 Successful Response
GET/api/v1/auth/onboardingIdentity waiting to create an organisationonboarding
The newly authenticated identity behind the onboarding cookie (no session exists yet).
Responses
200 Successful Response
GET/api/v1/auth/providersAvailable sign-in providerspublic
Responses
200 Successful Response

Name	Type	Required
code (query)	string \| null	no
state (query)	string \| null	no
error (query)	string \| null	no

Name	Type	Required	Notes
email	string (email)	yes
tenant_id	string (uuid) \| null	no

Name	Type	Required	Notes
return_to (query)	string \| null	no
signup (query)	boolean	no	default false

POST/api/v1/auth/signupCreate an account; emails a verification codepublic

Request body SignupIn

Name	Type	Required	Notes
email	string (email)	yes	0–254 characters
name	string	yes	2–120 characters
password	string	yes	0–256 characters
consent	boolean	no	default false
turnstile_token	string \| null	no	0–2048 characters
website	string	no	0–200 characters; default ""

Responses

202 Successful Response422 Validation Error

POST/api/v1/auth/signup/resendSend a new verification code (60-second cooldown)public
Request body EmailIn
Name Type Required Notes
email string (email) yes 0–254 characters
Responses
202 Successful Response422 Validation Error
POST/api/v1/auth/signup/verifyVerify the emailed code and activate the accountpublic
Request body VerifyIn
Name Type Required Notes
email string (email) yes 0–254 characters
code string yes 6–12 characters
Responses
200 Successful Response422 Validation Error
POST/api/v1/auth/switch-tenantSwitch to another organisation you belong tosigned in
Request body SwitchIn
Name Type Required Notes
tenant_id string (uuid) yes
Responses
204 Successful Response422 Validation Error
POST/api/v1/identities/tokenExchange agent client credentials for a short-lived, audience-bound workload tokenclient credentials
Request body TokenIn
Name Type Required Notes
grant_type "client_credentials" yes
client_id string yes 0–80 characters
client_secret string yes 0–200 characters
Responses
200 Successful Response422 Validation Error
GET/api/v1/tenants/currentCurrent Tenanttenant:read
Responses
200 Successful Response
PATCH/api/v1/tenants/currentUpdate Tenanttenant:manage
Request body TenantPatch
Name Type Required Notes
name string | null no 2–200 characters
Responses
200 Successful Response422 Validation Error
POST/api/v1/tenants/onboardCreate an organisationonboarding
Callable by a signed-in user (creates an additional organisation) or by a newly authenticated OIDC identity without an organisation (short-lived signed onboarding cookie).
Request body OnboardIn
Name Type Required Notes
name string yes 2–200 characters
slug string yes 3–63 characters
primary_region uk-south | eu-west | us-east yes
admin_display_name string yes 2–200 characters
Responses
201 Successful Response422 Validation Error

Name	Type	Required	Notes
tenant_id	string (uuid)	yes

Name	Type	Required	Notes
grant_type	"client_credentials"	yes
client_id	string	yes	0–80 characters
client_secret	string	yes	0–200 characters

Users, roles and settings

People in your organisation, roles and permissions, notifications and settings.

GET/api/v1/notificationsNotificationssigned in
Parameters
Name Type Required Notes
limit (query) integer no default 20
Responses
200 Successful Response422 Validation Error
POST/api/v1/notifications/{notification_id}/readMark Readsigned in
Parameters
Name Type Required Notes
notification_id (path) string (uuid) yes
Responses
204 Successful Response422 Validation Error
GET/api/v1/rolesList Rolesrole:read
Responses
200 Successful Response
GET/api/v1/roles/permissionsPermission catalogue and role matrixrole:read
Responses
200 Successful Response
GET/api/v1/settingsGet Settings Routesettings:read
Responses
200 Successful Response
PATCH/api/v1/settingsPatch Settingssettings:manage
Request body SettingsPatch
Name Type Required Notes
content_retention metadata_only | redacted_excerpts | null no
approval_ttl_seconds integer | null no 60 to 86400
Responses
200 Successful Response422 Validation Error
GET/api/v1/usersList Usersuser:read
Parameters
Name Type Required Notes
limit (query) integer no default 50
cursor (query) string | null no
q (query) string | null no
Responses
200 Successful Response422 Validation Error
POST/api/v1/usersInvite Useruser:manage
Request body UserIn
Name Type Required Notes
email string (email) yes
display_name string yes 2–200 characters
roles string[] yes
Responses
201 Successful Response422 Validation Error
PATCH/api/v1/users/{user_id}Patch Useruser:manage
Parameters
Name Type Required Notes
user_id (path) string (uuid) yes
Request body UserPatch
Name Type Required Notes
roles string[] | null no
status active | disabled | null no
display_name string | null no
Responses
200 Successful Response422 Validation Error

Name	Type	Required	Notes
limit (query)	integer	no	default 20

Name	Type	Required	Notes
notification_id (path)	string (uuid)	yes

Name	Type	Required	Notes
content_retention	metadata_only \| redacted_excerpts \| null	no
approval_ttl_seconds	integer \| null	no	60 to 86400

Name	Type	Required	Notes
email	string (email)	yes
display_name	string	yes	2–200 characters
roles	string[]	yes

Name	Type	Required	Notes
user_id (path)	string (uuid)	yes

Name	Type	Required
roles	string[] \| null	no
status	active \| disabled \| null	no
display_name	string \| null	no

Agent registry and identities

Registering agents, owners and versions; workload identities, delegations and permissions.

GET/api/v1/agentsList Agentsagent:read

Parameters

Name	Type	Required	Notes
limit (query)	integer	no	default 50
cursor (query)	string \| null	no
q (query)	string \| null	no
environment (query)	string \| null	no
status (query)	string \| null	no
risk_band (query)	string \| null	no
source (query)	string \| null	no

Responses

200 Successful Response422 Validation Error

POST/api/v1/agentsCreate Agentagent:write

Request body AgentIn

Name	Type	Required	Notes
name	string	yes	2–200 characters
slug	string \| null	no	0–100 characters
description	string	no	0–4000 characters; default ""
purpose	string	no	0–4000 characters; default ""
framework	string	no	0–64 characters; default "custom"
environment	production \| staging \| development	no	default "development"
business_unit	string \| null	no	0–120 characters
criticality	low \| medium \| high \| critical	no	default "medium"
data_classification	public \| internal \| confidential \| personal \| regulated \| restricted	no	default "internal"
internet_exposure	none \| controlled \| public	no	default "none"
code_execution	none \| sandboxed \| privileged	no	default "none"
persistent_memory	none \| bounded \| unbounded	no	default "none"
human_approval_coverage	strong \| partial \| none	no	default "none"
tags	string[]	no
owners	OwnerIn[]	no

Responses

201 Successful Response422 Validation Error

GET/api/v1/agents/{agent_id}Get Agentagent:read
Parameters
Name Type Required Notes
agent_id (path) string (uuid) yes
Responses
200 Successful Response422 Validation Error

PATCH/api/v1/agents/{agent_id}Patch Agentagent:write

Parameters

Name	Type	Required	Notes
agent_id (path)	string (uuid)	yes
If-Match (header)	string \| null	no

Request body AgentPatch

Name	Type	Required	Notes
name	string \| null	no	2–200 characters
description	string \| null	no	0–4000 characters
purpose	string \| null	no	0–4000 characters
framework	string \| null	no
environment	production \| staging \| development \| null	no
business_unit	string \| null	no
criticality	low \| medium \| high \| critical \| null	no
data_classification	public \| internal \| confidential \| personal \| regulated \| restricted \| null	no
internet_exposure	none \| controlled \| public \| null	no
code_execution	none \| sandboxed \| privileged \| null	no
persistent_memory	none \| bounded \| unbounded \| null	no
human_approval_coverage	strong \| partial \| none \| null	no
gateway_enforced	boolean \| null	no
tags	string[] \| null	no

Responses

200 Successful Response422 Validation Error

POST/api/v1/agents/{agent_id}/attestAttestagent:read
Parameters
Name Type Required Notes
agent_id (path) string (uuid) yes
Request body AttestIn
Name Type Required Notes
statement string yes 10–2000 characters
Responses
200 Successful Response422 Validation Error
GET/api/v1/agents/{agent_id}/containmentContainment Historyagent:read
Parameters
Name Type Required Notes
agent_id (path) string (uuid) yes
Responses
200 Successful Response422 Validation Error
POST/api/v1/agents/{agent_id}/delegationsAdd Delegationidentity:manage
Parameters
Name Type Required Notes
agent_id (path) string (uuid) yes
Request body DelegationIn
Name Type Required Notes
principal_ref string yes 3–320 characters
display_name string yes 1–200 characters
principal_type user | service no default "user"
scopes string[] yes
expires_at string (date-time) | null no
Responses
201 Successful Response422 Validation Error
POST/api/v1/agents/{agent_id}/gateway-accessGateway Accessagent:control
Parameters
Name Type Required Notes
agent_id (path) string (uuid) yes
Request body GatewayAccessIn
Name Type Required Notes
reason string yes
confirm boolean no default false
enabled boolean yes
Responses
200 Successful Response422 Validation Error
POST/api/v1/agents/{agent_id}/identitiesIssue Identityidentity:manage
Parameters
Name Type Required Notes
agent_id (path) string (uuid) yes
Responses
201 Successful Response422 Validation Error
POST/api/v1/agents/{agent_id}/ownersAdd Owneragent:write
Parameters
Name Type Required Notes
agent_id (path) string (uuid) yes
Request body OwnerAdd
Name Type Required Notes
name string yes 1–200 characters
email string (email) yes
owner_type accountable | technical | business no default "accountable"
Responses
201 Successful Response422 Validation Error

Name	Type	Required	Notes
statement	string	yes	10–2000 characters

Name	Type	Required	Notes
principal_ref	string	yes	3–320 characters
display_name	string	yes	1–200 characters
principal_type	user \| service	no	default "user"
scopes	string[]	yes
expires_at	string (date-time) \| null	no

Name	Type	Required	Notes
reason	string	yes
confirm	boolean	no	default false
enabled	boolean	yes

Name	Type	Required	Notes
name	string	yes	1–200 characters
email	string (email)	yes
owner_type	accountable \| technical \| business	no	default "accountable"

POST/api/v1/agents/{agent_id}/permissionsGrantidentity:manage

Parameters

Name	Type	Required	Notes
agent_id (path)	string (uuid)	yes

Request body GrantIn

Name	Type	Required	Notes
target_kind	tool \| api_resource \| data_resource \| credential \| model	yes
target_id	string (uuid)	yes
actions	string[]	yes
delegated	boolean	no	default false
constraints	object	no
expires_at	string (date-time) \| null	no
identity_id	string (uuid) \| null	no

Responses

201 Successful Response422 Validation Error

DELETE/api/v1/agents/{agent_id}/permissions/{binding_id}Revoke Permissionidentity:manage
Parameters
Name Type Required Notes
agent_id (path) string (uuid) yes
binding_id (path) string (uuid) yes
reason (query) string | null no 0–2000 characters
Responses
204 Successful Response422 Validation Error
POST/api/v1/agents/{agent_id}/restoreRestoreagent:control
Parameters
Name Type Required Notes
agent_id (path) string (uuid) yes
Request body ReasonIn
Name Type Required Notes
reason string yes
confirm boolean no default false
Responses
200 Successful Response422 Validation Error
POST/api/v1/agents/{agent_id}/revokePermanently revoke the agent and its identitiesagent:control
Parameters
Name Type Required Notes
agent_id (path) string (uuid) yes
Request body ReasonIn
Name Type Required Notes
reason string yes
confirm boolean no default false
Responses
200 Successful Response422 Validation Error
POST/api/v1/agents/{agent_id}/revoke-sessionsRevoke Sessionsagent:control
Parameters
Name Type Required Notes
agent_id (path) string (uuid) yes
Request body ReasonIn
Name Type Required Notes
reason string yes
confirm boolean no default false
Responses
200 Successful Response422 Validation Error
POST/api/v1/agents/{agent_id}/suspendKill switch: suspend the agent, revoke sessions and cancel pending approvalsagent:control
Parameters
Name Type Required Notes
agent_id (path) string (uuid) yes
Request body ReasonIn
Name Type Required Notes
reason string yes
confirm boolean no default false
Responses
200 Successful Response422 Validation Error
POST/api/v1/agents/{agent_id}/versionsAdd Versionagent:write
Parameters
Name Type Required Notes
agent_id (path) string (uuid) yes
Request body cydra__api__v1__registry__VersionIn
Name Type Required Notes
version_label string yes 1–64 characters
model_id string (uuid) | null no
manifest object no
change_summary string no 0–2000 characters; default ""
Responses
201 Successful Response422 Validation Error
GET/api/v1/identitiesList Identitiesidentity:read
Parameters
Name Type Required Notes
agent_id (query) string (uuid) | null no
Responses
200 Successful Response422 Validation Error
POST/api/v1/identities/{identity_id}/revokeRevoke Identityidentity:manage
Parameters
Name Type Required Notes
identity_id (path) string (uuid) yes
Request body ReasonIn
Name Type Required Notes
reason string yes
confirm boolean no default false
Responses
200 Successful Response422 Validation Error

Name	Type	Required	Notes
reason	string	yes
confirm	boolean	no	default false

Name	Type	Required	Notes
reason	string	yes
confirm	boolean	no	default false

Name	Type	Required	Notes
reason	string	yes
confirm	boolean	no	default false

Name	Type	Required	Notes
reason	string	yes
confirm	boolean	no	default false

Name	Type	Required	Notes
version_label	string	yes	1–64 characters
model_id	string (uuid) \| null	no
manifest	object	no
change_summary	string	no	0–2000 characters; default ""

Name	Type	Required	Notes
agent_id (query)	string (uuid) \| null	no

Inventory

Models, MCP servers, tools, API and data resources, and credential references.

GET/api/v1/mcp-serversList Serversinventory:read
Responses
200 Successful Response

POST/api/v1/mcp-serversCreate Serverinventory:write

Request body ServerIn

Name	Type	Required	Notes
name	string	yes	2–200 characters
endpoint	string	yes	8–500 characters
transport	streamable_http \| sse \| stdio	no	default "streamable_http"
auth_type	string	no	default "oauth"
publisher	string \| null	no

Responses

201 Successful Response422 Validation Error

PATCH/api/v1/mcp-servers/{server_id}Approve, distrust or quarantine an MCP serverinventory:control
Parameters
Name Type Required Notes
server_id (path) string (uuid) yes
Request body ServerPatch
Name Type Required Notes
trust_state approved | unknown | unsigned | quarantined yes
reason string yes 5–2000 characters
Responses
200 Successful Response422 Validation Error
GET/api/v1/modelsList Modelsinventory:read
Responses
200 Successful Response

POST/api/v1/modelsCreate Modelinventory:write

Request body ModelIn

Name	Type	Required	Notes
provider	string	yes	2–64 characters
model_name	string	yes	1–200 characters
model_version	string \| null	no
hosting	saas \| private \| customer_hosted	no	default "saas"
data_policy	string	no	default "unknown"

Responses

201 Successful Response422 Validation Error

PATCH/api/v1/models/{model_id}Patch Modelinventory:write
Parameters
Name Type Required Notes
model_id (path) string (uuid) yes
Request body ModelPatch
Name Type Required Notes
approved boolean | null no
max_data_classification public | internal | confidential | personal | regulated | restricted | null no
data_policy string | null no
Responses
200 Successful Response422 Validation Error
GET/api/v1/resourcesList Resourcesinventory:read
Responses
200 Successful Response

POST/api/v1/resources/apisCreate Api Resourceinventory:write

Request body ApiResourceIn

Name	Type	Required	Notes
name	string	yes	2–200 characters
system	string	yes	2–200 characters
base_url	string	yes	8–500 characters
auth_type	string	no	default "oauth_client_credentials"
criticality	low \| medium \| high \| critical	no	default "medium"

Responses

201 Successful Response422 Validation Error

GET/api/v1/resources/credentialsList Credentialsinventory:read
Responses
200 Successful Response

POST/api/v1/resources/credentialsCreate Credentialintegration:manage

Request body CredentialIn

Name	Type	Required	Notes
name	string	yes	2–200 characters
provider	vault \| aws_secrets_manager \| azure_key_vault \| gcp_secret_manager \| env \| mock	yes
secret_path	string	yes	Reference only; never the secret itself 1–500 characters
credential_type	api_key \| oauth_client \| token	no	default "api_key"
scope	string	no	default ""
shared	boolean	no	default false
rotation_interval_days	integer \| null	no	1 to 730

Responses

201 Successful Response422 Validation Error

POST/api/v1/resources/credentials/{credential_id}/actionCredential Actionagent:control
Parameters
Name Type Required Notes
credential_id (path) string (uuid) yes
Request body CredentialActionIn
Name Type Required Notes
reason string yes
confirm boolean no default false
action revoke | rotate yes
Responses
200 Successful Response422 Validation Error

POST/api/v1/resources/dataCreate Data Resourceinventory:write

Request body DataResourceIn

Name	Type	Required	Notes
name	string	yes	2–200 characters
kind	database \| bucket \| saas \| dataset \| document_store	no	default "database"
system	string	yes	2–200 characters
classification	public \| internal \| confidential \| personal \| regulated \| restricted	no	default "internal"
contains_personal_data	boolean	no	default false
region	string \| null	no

Responses

201 Successful Response422 Validation Error

GET/api/v1/toolsList Toolsinventory:read
Parameters
Name Type Required Notes
mcp_server_id (query) string (uuid) | null no
privilege_class (query) string | null no
Responses
200 Successful Response422 Validation Error

POST/api/v1/toolsCreate Toolinventory:write

Request body ToolIn

Name	Type	Required	Notes
tool_key	string	yes
name	string	yes	2–200 characters
description	string	no	0–4000 characters; default ""
mcp_server_id	string (uuid) \| null	no
api_resource_id	string (uuid) \| null	no
data_resource_id	string (uuid) \| null	no
operations	string[]	no
privilege_class	read \| write \| destructive \| financial \| admin	no	default "read"
approval_class	none \| single \| dual	no	default "none"
idempotent	boolean	no	default true
input_schema	object	no
credential_ref_id	string (uuid) \| null	no

Responses

201 Successful Response422 Validation Error

PATCH/api/v1/tools/{tool_id}Reclassify a tool (Cydra-assigned privilege overrides server annotations)inventory:write

Parameters

Name	Type	Required	Notes
tool_id (path)	string (uuid)	yes

Request body ToolPatch

Name	Type	Required	Notes
privilege_class	read \| write \| destructive \| financial \| admin \| null	no
approval_class	none \| single \| dual \| null	no
rate_limit_per_minute	integer \| null	no	1 to 10000
credential_ref_id	string (uuid) \| null	no

Responses

200 Successful Response422 Validation Error

POST/api/v1/tools/{tool_id}/blockBlock Toolinventory:control
Parameters
Name Type Required Notes
tool_id (path) string (uuid) yes
Request body BlockIn
Name Type Required Notes
reason string yes
confirm boolean no default false
blocked boolean yes
Responses
200 Successful Response422 Validation Error

Agent Security Graph

Nodes and edges, paths, transitive access, blast radius and high-risk paths.

GET/api/v1/graphGraph nodes and edges with search, filters and point-in-time viewgraph:read
Parameters
Name Type Required Notes
kinds (query) string | null no
q (query) string | null no
risk_levels (query) string | null no
at (query) string (date-time) | null no
limit (query) integer no default 2000
Responses
200 Successful Response422 Validation Error
GET/api/v1/graph/agents/{agent_id}Graph node for an agentgraph:read
Parameters
Name Type Required Notes
agent_id (path) string (uuid) yes
Responses
200 Successful Response422 Validation Error
GET/api/v1/graph/exportExportgraph:export
Parameters
Name Type Required Notes
format (query) json | csv no default "json"
part (query) nodes | edges no default "nodes"
at (query) string (date-time) | null no
Responses
200 Successful Response422 Validation Error
GET/api/v1/graph/high-risk-pathsHigh Riskgraph:read
Parameters
Name Type Required Notes
at (query) string (date-time) | null no
Responses
200 Successful Response422 Validation Error
GET/api/v1/graph/nodes/{node_id}Graph Nodegraph:read
Parameters
Name Type Required Notes
node_id (path) string (uuid) yes
Responses
200 Successful Response422 Validation Error
GET/api/v1/graph/nodes/{node_id}/accessTransitive access analysisgraph:read
Parameters
Name Type Required Notes
node_id (path) string (uuid) yes
at (query) string (date-time) | null no
Responses
200 Successful Response422 Validation Error
GET/api/v1/graph/nodes/{node_id}/blast-radiusBlastgraph:read
Parameters
Name Type Required Notes
node_id (path) string (uuid) yes
at (query) string (date-time) | null no
Responses
200 Successful Response422 Validation Error
GET/api/v1/graph/nodes/{node_id}/neighboursNeighboursgraph:read
Parameters
Name Type Required Notes
node_id (path) string (uuid) yes
depth (query) integer no default 1
at (query) string (date-time) | null no
Responses
200 Successful Response422 Validation Error
GET/api/v1/graph/pathShortest path between two nodesgraph:read
Parameters
Name Type Required Notes
source (query) string (uuid) yes
target (query) string (uuid) yes
directed (query) boolean no default false
at (query) string (date-time) | null no
Responses
200 Successful Response422 Validation Error
POST/api/v1/graph/rebuildRe-project the graph from the registryrisk:configure
Responses
200 Successful Response

Risk, findings and telemetry

Agent Risk Scores and what-if analysis, findings and the telemetry explorer.

GET/api/v1/findingsList Findingsfinding:read

Parameters

Name	Type	Required	Notes
limit (query)	integer	no	default 50
cursor (query)	string \| null	no
status (query)	string \| null	no
severity (query)	string \| null	no
agent_id (query)	string (uuid) \| null	no
category (query)	string \| null	no
q (query)	string \| null	no

Responses

200 Successful Response422 Validation Error

GET/api/v1/findings/{finding_id}Get Findingfinding:read
Parameters
Name Type Required Notes
finding_id (path) string (uuid) yes
Responses
200 Successful Response422 Validation Error
PATCH/api/v1/findings/{finding_id}Patch Findingfinding:write
Parameters
Name Type Required Notes
finding_id (path) string (uuid) yes
Request body FindingPatch
Name Type Required Notes
status open | in_progress | resolved | accepted | false_positive | null no
assigned_to string | null no 0–320 characters
note string | null no 0–2000 characters
Responses
200 Successful Response422 Validation Error
GET/api/v1/risks/agents/{agent_id}Latest explainable ARSrisk:read
Parameters
Name Type Required Notes
agent_id (path) string (uuid) yes
Responses
200 Successful Response422 Validation Error
GET/api/v1/risks/agents/{agent_id}/historyHistoryrisk:read
Parameters
Name Type Required Notes
agent_id (path) string (uuid) yes
days (query) integer no default 90
Responses
200 Successful Response422 Validation Error
POST/api/v1/risks/agents/{agent_id}/recalculateRecalcrisk:configure
Parameters
Name Type Required Notes
agent_id (path) string (uuid) yes
Responses
200 Successful Response422 Validation Error

POST/api/v1/risks/agents/{agent_id}/what-ifEffect of proposed remediation (no changes saved)risk:read

Parameters

Name	Type	Required	Notes
agent_id (path)	string (uuid)	yes

Request body WhatIfIn

Name	Type	Required	Notes
internet_exposure	none \| controlled \| public \| null	no
code_execution	none \| sandboxed \| privileged \| null	no
approval_coverage	strong \| partial \| none \| null	no
persistent_memory	none \| bounded \| unbounded \| null	no
production	boolean \| null	no
has_high_impact_tools	boolean \| null	no
has_privileged_tools	boolean \| null	no
has_write_tools	boolean \| null	no
gateway_enforced	boolean \| null	no
attestation_current	boolean \| null	no
delegation_breadth	none \| moderate \| broad \| null	no
max_data_classification	public \| internal \| confidential \| personal \| regulated \| restricted \| null	no
resolve_findings	boolean	no	default false
clear_detections	boolean	no	default false
approve_mcp_servers	boolean	no	default false
use_scoped_identity	boolean	no	default false

Responses

200 Successful Response422 Validation Error

GET/api/v1/risks/rulesetRisk factor definitions and weightsrisk:read
Responses
200 Successful Response
PATCH/api/v1/risks/ruleset/{factor_key}Tenant overlay: enable or disable a factorrisk:configure
Parameters
Name Type Required Notes
factor_key (path) string yes
Request body FactorToggle
Name Type Required Notes
enabled boolean yes
reason string yes 5–1000 characters
Responses
200 Successful Response422 Validation Error

GET/api/v1/telemetryTelemetrytelemetry:read

Parameters

Name	Type	Required	Notes
limit (query)	integer	no	default 100
cursor (query)	string \| null	no
event_type (query)	string \| null	no
agent_id (query)	string (uuid) \| null	no
severity (query)	string \| null	no
since (query)	string (date-time) \| null	no
until (query)	string (date-time) \| null	no
q (query)	string \| null	no
correlation_id (query)	string \| null	no

Responses

200 Successful Response422 Validation Error

GET/api/v1/telemetry/statsTelemetry Statstelemetry:read
Parameters
Name Type Required Notes
hours (query) integer no default 24
Responses
200 Successful Response422 Validation Error

Policies

Policy versions, four-eyes publishing and decision simulation.

GET/api/v1/policiesList Policiespolicy:read
Responses
200 Successful Response

POST/api/v1/policiesCreate Policypolicy:write

Request body PolicyIn

Name	Type	Required	Notes
key	string	yes	3–100 characters
name	string	yes	3–200 characters
description	string	no	0–2000 characters; default ""
critical	boolean	no	default false
rules	Rule[]	yes
change_note	string	no	0–2000 characters; default "Initial draft"

Responses

201 Successful Response422 Validation Error

GET/api/v1/policies/{policy_id}Get Policypolicy:read
Parameters
Name Type Required Notes
policy_id (path) string (uuid) yes
Responses
200 Successful Response422 Validation Error
POST/api/v1/policies/{policy_id}/statusSet Statuspolicy:publish
Parameters
Name Type Required Notes
policy_id (path) string (uuid) yes
If-Match (header) string | null no
Request body StatusIn
Name Type Required Notes
status active | inactive yes
Responses
200 Successful Response422 Validation Error
POST/api/v1/policies/{policy_id}/versionsCreate a draft version (requires If-Match with the policy version)policy:write
Parameters
Name Type Required Notes
policy_id (path) string (uuid) yes
If-Match (header) string | null no
Request body cydra__api__v1__gateway__VersionIn
Name Type Required Notes
rules Rule[] yes
change_note string yes 3–2000 characters
Responses
201 Successful Response422 Validation Error
POST/api/v1/policies/{policy_id}/versions/{number}/publishPublish a draft (four-eyes: publisher must differ from author)policy:publish
Parameters
Name Type Required Notes
policy_id (path) string (uuid) yes
number (path) integer yes
If-Match (header) string | null no
Responses
200 Successful Response422 Validation Error
GET/api/v1/policies/operatorsOperatorspolicy:read
Responses
200 Successful Response

POST/api/v1/policies/simulateDry-run a decision (nothing is persisted or executed)action:test

Request body SimulateIn

Name	Type	Required	Notes
agent_id	string (uuid)	yes
tool	string	yes	1–200 characters
operation	string	no	0–100 characters; default "invoke"
target	string	no	0–500 characters; default ""
parameters	object	no
environment	string \| null	no
on_behalf_of	string \| null	no
justification	string \| null	no	0–2000 characters
draft_rules	Rule[] \| null	no	Evaluate these rules instead of the active set
approval_present	boolean	no	default false

Responses

200 Successful Response422 Validation Error

Gateway: actions, decisions and approvals

Submitting actions (agents), the testing console, decisions, executions and approvals.

GET/api/v1/actionsList Actionsaction:read

Parameters

Name	Type	Required	Notes
limit (query)	integer	no	default 50
cursor (query)	string \| null	no
agent_id (query)	string (uuid) \| null	no
state (query)	string \| null	no
decision (query)	string \| null	no
tool (query)	string \| null	no

Responses

200 Successful Response422 Validation Error

POST/api/v1/actionsGateway: submit a consequential action for authorisation (agent workload token)agent token

Parameters

Name	Type	Required	Notes
Idempotency-Key (header)	string	yes	8–200 characters

Request body ActionIn

Name	Type	Required	Notes
tool	string	yes	1–200 characters
operation	string	no	1–100 characters; default "invoke"
target	string	yes	1–500 characters
parameters	object	no
environment	production \| staging \| development \| null	no
on_behalf_of	string \| null	no	0–320 characters
justification	string \| null	no	0–2000 characters
approval_token	string \| null	no	0–4000 characters

Responses

200 Successful Response422 Validation Error

GET/api/v1/actions/{action_id}Get Actionaction:read
Parameters
Name Type Required Notes
action_id (path) string (uuid) yes
Responses
200 Successful Response422 Validation Error
POST/api/v1/actions/{action_id}/cancelCancelaction:control
Parameters
Name Type Required Notes
action_id (path) string (uuid) yes
Request body ReasonIn
Name Type Required Notes
reason string yes
confirm boolean no default false
Responses
200 Successful Response422 Validation Error

POST/api/v1/actions/consoleGateway testing console: submit an action on behalf of an agent (simulated executors)action:test

Parameters

Name	Type	Required	Notes
Idempotency-Key (header)	string	yes	8–200 characters

Request body ConsoleActionIn

Name	Type	Required	Notes
tool	string	yes	1–200 characters
operation	string	no	1–100 characters; default "invoke"
target	string	yes	1–500 characters
parameters	object	no
environment	production \| staging \| development \| null	no
on_behalf_of	string \| null	no	0–320 characters
justification	string \| null	no	0–2000 characters
approval_token	string \| null	no	0–4000 characters
agent_id	string (uuid)	yes

Responses

200 Successful Response422 Validation Error

POST/api/v1/actions/deny-classContainment: deny an action class for all agents or one agentaction:control
Request body DenyClassIn
Name Type Required Notes
reason string yes
confirm boolean no default false
privilege_class read | write | destructive | financial | admin yes
agent_id string (uuid) | null no
Responses
200 Successful Response422 Validation Error
POST/api/v1/actions/deny-class/liftLiftaction:control
Request body LiftIn
Name Type Required Notes
reason string yes
confirm boolean no default false
rule_id string yes
Responses
200 Successful Response422 Validation Error
GET/api/v1/actions/gateway/{action_id}Gateway: action status for the requesting agent, including a single-use approval token once approvedagent token
Parameters
Name Type Required Notes
action_id (path) string (uuid) yes
Responses
200 Successful Response422 Validation Error
GET/api/v1/approvalsList Approvalsapproval:read
Parameters
Name Type Required Notes
status (query) string | null no default "pending"
limit (query) integer no default 50
cursor (query) string | null no
Responses
200 Successful Response422 Validation Error
GET/api/v1/approvals/{approval_id}Get Approvalapproval:read
Parameters
Name Type Required Notes
approval_id (path) string (uuid) yes
Responses
200 Successful Response422 Validation Error
POST/api/v1/approvals/{approval_id}/decisionDecide Approvalapproval:decide
Parameters
Name Type Required Notes
approval_id (path) string (uuid) yes
Request body DecisionIn
Name Type Required Notes
decision approve | reject yes
reason string yes 3–2000 characters
Responses
200 Successful Response422 Validation Error
GET/api/v1/decisionsList Decisionsaction:read
Parameters
Name Type Required Notes
limit (query) integer no default 50
cursor (query) string | null no
decision (query) string | null no
Responses
200 Successful Response422 Validation Error
GET/api/v1/executionsList Executionsaction:read
Parameters
Name Type Required Notes
limit (query) integer no default 50
cursor (query) string | null no
Responses
200 Successful Response422 Validation Error

Evidence and governance

The evidence chain, frameworks and controls, exceptions, remediation and the audit log.

GET/api/v1/auditAuditaudit:read

Parameters

Name	Type	Required	Notes
limit (query)	integer	no	default 50
cursor (query)	string \| null	no
action (query)	string \| null	no
actor_id (query)	string \| null	no
outcome (query)	string \| null	no
target_id (query)	string \| null	no

Responses

200 Successful Response422 Validation Error

GET/api/v1/controls/{control_id}Controlgovernance:read
Parameters
Name Type Required Notes
control_id (path) string (uuid) yes
Responses
200 Successful Response422 Validation Error
POST/api/v1/controls/{control_id}/mappingsAdd Mappinggovernance:write
Parameters
Name Type Required Notes
control_id (path) string (uuid) yes
Request body MappingIn
Name Type Required Notes
evidence_event_type string yes 3–80 characters
condition object no
rationale string yes 5–1000 characters
Responses
201 Successful Response422 Validation Error

GET/api/v1/evidenceList Evidenceevidence:read

Parameters

Name	Type	Required	Notes
limit (query)	integer	no	default 50
cursor (query)	string \| null	no
event_type (query)	string \| null	no
agent_id (query)	string (uuid) \| null	no
control_ref (query)	string \| null	no
action_request_id (query)	string (uuid) \| null	no

Responses

200 Successful Response422 Validation Error

GET/api/v1/evidence/{evidence_id}Get Evidenceevidence:read
Parameters
Name Type Required Notes
evidence_id (path) string (uuid) yes
Responses
200 Successful Response422 Validation Error
GET/api/v1/evidence/verifyRecompute the tenant's hash-linked evidence chainevidence:read
Responses
200 Successful Response
GET/api/v1/exceptionsList Exceptionsgovernance:read
Parameters
Name Type Required Notes
status (query) string | null no
Responses
200 Successful Response422 Validation Error

POST/api/v1/exceptionsRequest Exceptiongovernance:write

Request body ExceptionIn

Name	Type	Required	Notes
control_id	string (uuid)	yes
agent_id	string (uuid) \| null	no
title	string	yes	5–300 characters
justification	string	yes	20–4000 characters
compensating_controls	string	no	0–4000 characters; default ""
owner_email	string (email)	yes
expires_at	string (date-time)	yes

Responses

201 Successful Response422 Validation Error

POST/api/v1/exceptions/{exception_id}/decisionDecide Exceptionexception:approve
Parameters
Name Type Required Notes
exception_id (path) string (uuid) yes
Request body ExceptionDecision
Name Type Required Notes
decision approve | reject yes
note string yes 3–2000 characters
Responses
200 Successful Response422 Validation Error
GET/api/v1/governance/frameworksFrameworks with control coverage and readinessgovernance:read
Responses
200 Successful Response
GET/api/v1/governance/remediationRemediationgovernance:read
Parameters
Name Type Required Notes
status (query) string | null no
agent_id (query) string (uuid) | null no
Responses
200 Successful Response422 Validation Error

POST/api/v1/governance/remediationCreate Taskgovernance:write

Request body TaskIn

Name	Type	Required	Notes
title	string	yes	5–300 characters
description	string	no	0–4000 characters; default ""
control_id	string (uuid) \| null	no
agent_id	string (uuid) \| null	no
finding_id	string (uuid) \| null	no
assignee_email	string (email) \| null	no
due_at	string (date-time) \| null	no
priority	low \| medium \| high \| critical	no	default "medium"

Responses

201 Successful Response422 Validation Error

PATCH/api/v1/governance/remediation/{task_id}Patch Taskgovernance:write
Parameters
Name Type Required Notes
task_id (path) string (uuid) yes
Request body TaskPatch
Name Type Required Notes
status open | in_progress | done | cancelled | null no
assignee_email string (email) | null no
Responses
200 Successful Response422 Validation Error
GET/api/v1/governance/systemsAI-system classification registergovernance:read
Responses
200 Successful Response
POST/api/v1/governance/systems/{agent_id}/classifyClassify an AI system; returns remediation tasks generated for evidence gapsgovernance:write
Parameters
Name Type Required Notes
agent_id (path) string (uuid) yes
Request body ClassifyIn
Name Type Required Notes
classification unclassified | minimal | limited | high | prohibited yes
rationale string yes 10–4000 characters
Responses
200 Successful Response422 Validation Error

Integrations and reports

Integrations, discovery connectors and reports.

POST/api/v1/connectors/{connector_id}/enabledConnector Enabledintegration:manage
Parameters
Name Type Required Notes
connector_id (path) string (uuid) yes
Request body ConnectorEnable
Name Type Required Notes
reason string yes
confirm boolean no default false
enabled boolean yes
Responses
200 Successful Response422 Validation Error
POST/api/v1/connectors/{connector_id}/runRun discovery nowconnector:run
Parameters
Name Type Required Notes
connector_id (path) string (uuid) yes
Request body RunIn
Name Type Required Notes
idempotency_key string | null no 0–200 characters
Responses
200 Successful Response422 Validation Error
GET/api/v1/connectors/{connector_id}/runsRunsintegration:read
Parameters
Name Type Required Notes
connector_id (path) string (uuid) yes
Responses
200 Successful Response422 Validation Error
GET/api/v1/dashboardExecutive security dashboard metricsagent:read
Parameters
Name Type Required Notes
days (query) integer no default 30
Responses
200 Successful Response422 Validation Error
GET/api/v1/integrationsList Integrationsintegration:read
Responses
200 Successful Response
POST/api/v1/integrationsCreate Integrationintegration:manage
Request body IntegrationIn
Name Type Required Notes
kind openai | anthropic | mcp | entra_id | github | webhook yes
name string yes 2–200 characters
mode live | mock no default "mock"
config object no
credential_ref_id string (uuid) | null no
Responses
201 Successful Response422 Validation Error
POST/api/v1/integrations/{integration_id}/statusIntegration Statusintegration:manage
Parameters
Name Type Required Notes
integration_id (path) string (uuid) yes
Request body IntegrationStatus
Name Type Required Notes
reason string yes
confirm boolean no default false
status active | disabled yes
Responses
200 Successful Response422 Validation Error
GET/api/v1/integrations/catalogueCatalogueintegration:read
Responses
200 Successful Response
GET/api/v1/reportsList Reportsreport:read
Responses
200 Successful Response
POST/api/v1/reportsCreate Reportreport:create
Request body ReportIn
Name Type Required Notes
kind executive_summary | agent_inventory | risk_register | governance_readiness | evidence_bundle yes
parameters object no
Responses
201 Successful Response422 Validation Error
GET/api/v1/reports/{report_id}/downloadDownloadreport:read
Parameters
Name Type Required Notes
report_id (path) string (uuid) yes
Responses
200 Successful Response422 Validation Error
GET/api/v1/reports/kindsReport Kindsreport:read
Responses
200 Successful Response

Public website endpoints

Unauthenticated endpoints used by the website (rate-limited).

GET/api/v1/public/form-configPublic site settings: Turnstile site key, analytics and docs URLpublic
Responses
200 Successful Response

POST/api/v1/public/leadsWebsite request: demo, contact, support or risk self-assessmentpublic

Request body LeadIn

Name	Type	Required	Notes
kind	demo \| assessment	yes
request_type	demo \| risk-assessment \| support \| partnership \| other \| null	no
topic	demo \| contact \| design-partner \| mcp-security-workshop \| architecture-consultation \| governance-readiness-review \| cydrasoc-demo \| devsec-pilot \| industry-discovery \| security-packs-pilot \| industry-packs-pilot \| security-report \| null	no
name	string	yes	2–120 characters
email	string (email)	yes	0–254 characters
company	string	yes	2–160 characters
role	string \| null	no	0–120 characters
message	string \| null	no	0–4000 characters
consent	boolean	no	default false
source_page	string \| null	no	0–200 characters
turnstile_token	string \| null	no	0–2048 characters
assessment	object \| null	no
website	string	no	0–200 characters; default ""

Responses

202 Successful Response422 Validation Error

GET/api/v1/public/pricingPublished indicative pricing (schema version 1)public
Responses
200 Successful Response

POST/api/v1/public/pricing-quoteRequest a pricing quotationpublic

Request body QuoteIn

Name	Type	Required	Notes
full_name	string	yes	2–120 characters
work_email	string (email)	yes	0–254 characters
company	string	yes	2–160 characters
job_title	string	yes	2–120 characters
country	string	yes	2–80 characters
estimated_agents	integer	yes	1 to 1000000
tier	string \| null	no	0–40 characters
products	string[]	no
deployment_model	string	yes	0–40 characters
retention_period	string	yes	0–40 characters
message	string	no	0–4000 characters; default ""
privacy_consent	boolean	yes
website	string	no	0–200 characters; default ""

Responses

202 Successful Response422 Validation Error

Applies to the CydraLabs proof-of-concept platform. Last updated 4 October 2026. Questions or corrections: contact us.

Name	Type	Required	Notes
agent_id (path)	string (uuid)	yes
binding_id (path)	string (uuid)	yes
reason (query)	string \| null	no	0–2000 characters

Name	Type	Required	Notes
trust_state	approved \| unknown \| unsigned \| quarantined	yes
reason	string	yes	5–2000 characters

Name	Type	Required
approved	boolean \| null	no
max_data_classification	public \| internal \| confidential \| personal \| regulated \| restricted \| null	no
data_policy	string \| null	no

Name	Type	Required	Notes
mcp_server_id (query)	string (uuid) \| null	no
privilege_class (query)	string \| null	no

Name	Type	Required	Notes
kinds (query)	string \| null	no
q (query)	string \| null	no
risk_levels (query)	string \| null	no
at (query)	string (date-time) \| null	no
limit (query)	integer	no	default 2000

Name	Type	Required	Notes
format (query)	json \| csv	no	default "json"
part (query)	nodes \| edges	no	default "nodes"
at (query)	string (date-time) \| null	no

Name	Type	Required	Notes
node_id (path)	string (uuid)	yes
at (query)	string (date-time) \| null	no

Name	Type	Required	Notes
node_id (path)	string (uuid)	yes
depth (query)	integer	no	default 1
at (query)	string (date-time) \| null	no

Name	Type	Required	Notes
source (query)	string (uuid)	yes
target (query)	string (uuid)	yes
directed (query)	boolean	no	default false
at (query)	string (date-time) \| null	no

Name	Type	Required	Notes
status	open \| in_progress \| resolved \| accepted \| false_positive \| null	no
assigned_to	string \| null	no	0–320 characters
note	string \| null	no	0–2000 characters

Name	Type	Required	Notes
agent_id (path)	string (uuid)	yes
days (query)	integer	no	default 90

Name	Type	Required	Notes
policy_id (path)	string (uuid)	yes
If-Match (header)	string \| null	no

Name	Type	Required
policy_id (path)	string (uuid)	yes
number (path)	integer	yes
If-Match (header)	string \| null	no

Name	Type	Required	Notes
status (query)	string \| null	no	default "pending"
limit (query)	integer	no	default 50
cursor (query)	string \| null	no

Name	Type	Required	Notes
decision	approve \| reject	yes
reason	string	yes	3–2000 characters

Name	Type	Required	Notes
evidence_event_type	string	yes	3–80 characters
condition	object	no
rationale	string	yes	5–1000 characters

Name	Type	Required	Notes
status	open \| in_progress \| done \| cancelled \| null	no
assignee_email	string (email) \| null	no

Name	Type	Required	Notes
classification	unclassified \| minimal \| limited \| high \| prohibited	yes
rationale	string	yes	10–4000 characters

Name	Type	Required	Notes
kind	openai \| anthropic \| mcp \| entra_id \| github \| webhook	yes
name	string	yes	2–200 characters
mode	live \| mock	no	default "mock"
config	object	no
credential_ref_id	string (uuid) \| null	no

Name	Type	Required	Notes
kind	executive_summary \| agent_inventory \| risk_register \| governance_readiness \| evidence_bundle	yes
parameters	object	no