Reference

API Reference

Trigger workflow executions and retrieve execution traces from your own applications, backend services, or CI pipelines using the CipherSense Agents REST API.

Base URLhttps://agents.ciphersense.ai

Authentication

All API requests must be authenticated with an API key passed as a Bearer token in the Authorization header. API keys are scoped to an organisation — a key can only trigger workflows that belong to the same organisation it was created in.

Keep your key secret

API keys are shown in full only once, immediately after creation. They are stored as a one-way hash — if you lose the key you must revoke it and generate a new one. Never embed keys in client-side code or commit them to source control.

Generating a key

Navigate to Organisation Settings → API Keys and click New API Key. Only organisation Admins can create and revoke keys. Keys follow the format cs_live_<48 hex chars>.

Request header

Authorization: Bearer cs_live_3f9a...c2d1

CodeMeaning

401Missing or invalid API key. Check the Authorization header format and ensure the key has not been revoked.

403The API key is valid but does not have access to the requested resource (e.g. the workflow belongs to a different organisation).

List Workflows

Returns a paginated list of all active (non-archived, non-deleted) workflows that belong to the organisation associated with your API key. Useful for discovering workflow IDs before triggering a run.

GEThttps://agents.ciphersense.ai/api/workflows/list

Query parameters

ParameterTypeDescription

projectIdstringFilter results to a single project UUID. Omit to return workflows across all projects in the organisation.

limitintegerNumber of results per page. Default: 20. Maximum: 100.

offsetintegerZero-based offset for pagination. Default: 0.

Example request

curl "https://agents.ciphersense.ai/api/workflows/list?limit=10&offset=0" \
  -H "Authorization: Bearer cs_live_3f9a...c2d1"

200 Response

{
  "workflows": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Nightly Report Generator",
      "description": "Generates and emails a usage summary each night.",
      "status": "active",
      "schedule_type": "daily",
      "webhook_enabled": false,
      "created_at": "2025-01-10T09:00:00Z",
      "updated_at": "2025-03-02T14:30:00Z",
      "last_executed_at": "2025-03-17T00:05:00Z",
      "project": {
        "id": "proj_9f1e...",
        "name": "Data Ops"
      }
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

Response fields

FieldTypeDescription

workflowsarrayArray of workflow objects for the current page.

totalintegerTotal number of matching workflows across all pages.

limitintegerThe page size that was applied.

offsetintegerThe offset that was applied.

CodeMeaning

200Paginated workflow list returned.

400organizationId is missing (session auth only).

403API key does not have access to the requested organisation, or session user is not a member.

429Rate limit exceeded. Up to 60 requests per minute are allowed.

Run a Workflow

Triggers a new execution of the specified workflow. Execution is asynchronous — the request returns immediately with an executionId while the workflow runs in the background. Use the execution ID to poll for status or retrieve the trace.

POSThttps://agents.ciphersense.ai/api/workflows/run

Request body

FieldTypeDescription

workflowIdstringrequiredThe UUID of the workflow to run. Found in the workflow URL in the dashboard.

Example request

curl -X POST https://agents.ciphersense.ai/api/workflows/run \
  -H "Authorization: Bearer cs_live_3f9a...c2d1" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

202 Response

{
  "executionId": "exec_7f3a91bc-...",
  "status": "running",
  "message": "Workflow execution started in background."
}

CodeMeaning

202Execution created and running in background. The executionId is returned immediately.

400Missing workflowId, or the organisation has no LLM providers configured.

402Monthly token quota or workflow run limit exceeded for the organisation's plan.

404Workflow not found.

409The workflow is already running or awaiting human input. Cancel the active execution before starting a new one.

Get Execution Trace

Retrieves the full execution record and step-level trace for a given execution ID. Poll this endpoint after calling Run a Workflow to check whether execution has completed and to inspect per-node results, durations, and any errors.

GEThttps://agents.ciphersense.ai/api/workflows/executions/{execution_id}

Path parameter

ParameterTypeDescription

execution_idstringrequiredThe executionId returned by the Run Workflow endpoint.

Example request

curl https://agents.ciphersense.ai/api/workflows/executions/exec_7f3a91bc-... \
  -H "Authorization: Bearer cs_live_3f9a...c2d1"

200 Response

{
  "id": "exec_7f3a91bc-...",
  "workflow_id": "a1b2c3d4-...",
  "status": "success",
  "created_at": "2025-03-17T10:22:00Z",
  "duration_ms": 4821,
  "total_tokens": 1340,
  "steps": [
    {
      "id": "step_001",
      "node_id": "node-abc",
      "node_type": "integration",
      "status": "success",
      "duration_ms": 312,
      "output_data": { "content": "...", "data": "..." }
    },
    {
      "id": "step_002",
      "node_id": "node-xyz",
      "node_type": "agent",
      "status": "success",
      "duration_ms": 4509,
      "input_data": {
        "prompt": "Analyse the following data: ...",
        "resolved_variables": { "data": "..." }
      },
      "output_data": { "content": "Here are the key trends..." }
    }
  ]
}

Execution status values

running

Workflow is actively executing.

success

All nodes completed successfully.

failed

One or more nodes encountered an error.

awaiting_input

Paused at a Human-in-the-Loop node, waiting for approval.

cancelled

Execution was cancelled manually before completion.

CodeMeaning

200Execution record and step trace returned.

403API key does not belong to the same organisation as the execution.

404Execution ID not found.

Ready to integrate?

Generate your first API key from Organisation Settings and trigger a workflow run from your own service in minutes.

Open Dashboard Read: Workflows