API Reference¶

Base URL:

Hosted: https://api.pisama.ai/api/v1
Self-hosted: http://localhost:8000/api/v1 (after docker compose up)

Product capability contract¶

GET /billing/capabilities is public and returns the canonical product vocabulary, license categories, deployment models, runtime-specific features, allowances, and upgrade boundaries for the main and n8n product families.

The same document is available as static JSON at pisama.ai/product-capabilities.json. Use the stable capability IDs instead of matching customer-facing labels.

All authenticated endpoints require either an API key (X-Pisama-API-Key header) or a JWT Bearer token. Tenant-scoped endpoints include {tenant_id} in the path.

Health¶

`GET /health`¶

App-level liveness check (no dependencies).

Auth: None
Response: { "status": "healthy" }

`GET /api/v1/health`¶

Full health check including database and Redis. Returns 503 when the database is unreachable and degraded when Redis is unreachable.

Auth: None
Response: { "status": "healthy|degraded|unhealthy", "database": "healthy|unhealthy", "redis": "healthy|unhealthy", "version": "string" }

Traces¶

Prefix: /tenants/{tenant_id}/traces

`POST /traces/ingest`¶

Ingest OpenTelemetry spans. Returns 202 Accepted. Auto-rejects with 503 under backpressure.

Body: OTEL span export format (JSON)

`GET /traces`¶

List traces with pagination and filtering.

Query: page, page_size, agent_id, date_from, date_to, status

`GET /traces/{trace_id}`¶

Get single trace with all spans.

`GET /traces/{trace_id}/states`¶

Get all state snapshots in a trace.

`POST /traces/{trace_id}/analyze`¶

Run all detection algorithms on a trace. Returns detection results.

Conversations¶

Prefix: /tenants/{tenant_id}/conversations

`POST /conversations/ingest`¶

Ingest a conversation trace. Supports formats: mast-data, openai, claude, generic.

Body: { "format": "string", "data": {...} }

`GET /conversations`¶

List conversation traces with pagination.

`GET /conversations/{conversation_id}`¶

Get conversation details.

`GET /conversations/{conversation_id}/turns`¶

Get turn-by-turn breakdown.

`POST /conversations/{conversation_id}/analyze`¶

Run turn-aware detection algorithms.

Detections¶

Prefix: /tenants/{tenant_id}/detections

`GET /detections`¶

List detections with pagination and filtering.

Query: detection_type, validated, confidence_min, confidence_max, trace_id, date_from, date_to, page, page_size

`GET /detections/{detection_id}`¶

Get single detection with explanation and evidence.

`POST /detections/{detection_id}/validate`¶

Mark a detection as validated (true positive or false positive).

Body: { "is_valid": true, "feedback": "optional note" }

`GET /detections/{detection_id}/fixes`¶

Get AI-generated fix suggestions for a detection.

`POST /detections/{detection_id}/fixes/{fix_id}/apply`¶

Record that a fix was applied.

Agents¶

`GET /tenants/{tenant_id}/agents`¶

List agents derived from trace data with stats.

Response: Array of { agent_id, step_count, tokens_used, avg_latency_ms, last_active_at, status }

Analytics¶

Prefix: /tenants/{tenant_id}/analytics

`GET /analytics/loops`¶

Loop detection statistics: method breakdown, affected agents, time series.

Query: days (1-365, default 30)

`GET /analytics/cost`¶

Cost breakdown by framework and daily trends.

Query: days

`GET /analytics/quality`¶

Quality assessment stats: score distribution, grades, trends.

Query: days

Feedback¶

Prefix: /tenants/{tenant_id}/feedback

`POST /feedback`¶

Submit feedback on detection accuracy.

Body: { "detection_id": "uuid", "is_correct": true, "reason": "optional note", "severity_rating": 3 } (is_correct is required; severity_rating is 1-5; the response derives feedback_type from is_correct)
Response: 201

`GET /feedback/stats`¶

Aggregated feedback statistics (precision, recall, F1 per detection type).

`GET /feedback/recommendations`¶

Threshold adjustment recommendations based on accumulated feedback.

`GET /feedback`¶

List feedback submissions with pagination.

Healing¶

Prefix: /tenants/{tenant_id}/healing

`GET /healing`¶

List self-healing operations.

Query: status, page, per_page

`POST /healing/trigger/{detection_id}`¶

Generate a fix for a detection and start a healing operation.

`GET /healing/{healing_id}/status`¶

Get the current status of a healing operation.

`GET /healing/{healing_id}/progress`¶

Get step-by-step progress for a healing operation.

`POST /healing/{healing_id}/approve`¶

Approve a generated fix for application (manual-approval policies).

`POST /healing/{healing_id}/reject`¶

Reject a generated fix.

`POST /healing/{healing_id}/verify`¶

Run post-fix verification on a healing operation.

`POST /healing/{healing_id}/promote`¶

Promote a verified fix.

`POST /healing/{healing_id}/complete`¶

Mark a healing operation complete.

`POST /healing/{healing_id}/rollback`¶

Roll back a previously applied fix.

`GET /healing/stats`¶

Aggregated healing statistics.

Settings¶

Prefix: /tenants/{tenant_id}/settings

`GET /settings/thresholds`¶

Get current detection threshold settings.

`PUT /settings/thresholds`¶

Update detection thresholds.

Body: { "structural_threshold": 0.95, "semantic_threshold": 0.85, "loop_detection_window": 7, ... }

`DELETE /settings/thresholds`¶

Reset thresholds to defaults. Optional framework query param for per-framework reset.

`GET /settings/thresholds/defaults`¶

Get default thresholds (public, no auth required).

`GET /settings/thresholds/preview`¶

Preview effective thresholds with proposed changes applied.

Workflow Groups¶

Prefix: /tenants/{tenant_id}/workflow-groups

`POST /workflow-groups`¶

Create a workflow group with auto-detection rules.

`GET /workflow-groups`¶

List workflow groups.

`GET /workflow-groups/{group_id}`¶

Get group details.

`PUT /workflow-groups/{group_id}`¶

Update group settings.

`DELETE /workflow-groups/{group_id}`¶

Delete a group.

`POST /workflow-groups/{group_id}/assign`¶

Manually assign workflows to a group.

`POST /workflow-groups/{group_id}/auto-detect`¶

Auto-assign workflows by matching rules (name pattern, source, complexity, grade).

ATIF Analysis¶

Prefix: /atif

`POST /atif/analyze`¶

Parse one Agent Trajectory Interchange Format (ATIF) v1.x trajectory and run Pisama's detector pipeline without persisting the trajectory.

Canonical URL: /api/v1/atif/analyze
Authentication: bearer token
Body:

{
  "trajectory": {
    "schema_version": "ATIF-v1.7",
    "agent": {"name": "my-agent"},
    "steps": []
  },
  "project_id": null,
  "detectors": null
}

detectors can contain an allowlist of detector names. When omitted, the full applicable suite runs. The response contains diagnosis, a parsed trace summary, topology completeness, unresolved trajectory references, and an optional healing result.

The stateless endpoint does not fetch paths named in the trajectory. Use the Python Agent SDK batch client to discover a Harbor job directory and safely resolve local continuation files. See the Harbor integration guide.

n8n Integration¶

Prefix: /n8n

`POST /n8n/webhook`¶

Receive n8n execution webhook. Requires X-Pisama-API-Key header.

Verification headers: X-Pisama-Signature, X-Pisama-Timestamp, X-Pisama-Nonce

`POST /n8n/workflows`¶

Register an n8n workflow for monitoring.

`GET /n8n/workflows`¶

List registered n8n workflows.

`POST /n8n/sync`¶

Pull historical executions from n8n cloud.

`GET /n8n/sync/status`¶

Get n8n sync configuration status.

`POST /n8n/discover`¶

Discover workflows from a connected n8n instance.

`GET /n8n/stream`¶

SSE endpoint for real-time execution updates.

Dify Integration¶

Prefix: /dify

`POST /dify/webhook`¶

Receive Dify workflow execution webhook.

`POST /dify/instances` / `GET /dify/instances`¶

Register and list Dify instance connections.

`POST /dify/apps` / `GET /dify/apps`¶

Register and list Dify apps for monitoring.

`GET /dify/stream`¶

SSE endpoint for real-time execution updates.

LangGraph Integration¶

Prefix: /langgraph

`POST /langgraph/webhook`¶

Receive LangGraph deployment webhook.

`POST /langgraph/deployments` / `GET /langgraph/deployments`¶

Register and list LangGraph deployments.

`POST /langgraph/assistants` / `GET /langgraph/assistants`¶

Register and list LangGraph assistants.

`GET /langgraph/stream`¶

SSE endpoint for real-time execution updates.

OpenClaw Integration¶

Prefix: /openclaw

`POST /openclaw/webhook`¶

Receive OpenClaw agent session webhook.

`POST /openclaw/instances` / `GET /openclaw/instances`¶

Register and list OpenClaw instances.

`POST /openclaw/agents` / `GET /openclaw/agents`¶

Register and list OpenClaw agents.

`GET /openclaw/stream`¶

SSE endpoint for real-time execution updates.

Claude Code Integration¶

`POST /traces/claude-code/ingest`¶

Ingest traces from Claude Code CLI sessions.

Body: { "timestamp", "tool_name", "hook_type", "session_id", "tool_input", "tool_output", "working_dir", "trace_type", "model", "tokens_in", "tokens_out", "cost_usd" }

Security¶

Prefix: /security

`POST /security/injection/check`¶

Check text for prompt injection attempts.

Body: { "text": "string" }

`POST /security/hallucination/check`¶

Check output against sources for hallucination.

Body: { "output": "string", "sources": ["string"] }

`POST /security/overflow/check`¶

Check for context window overflow risk.

Body: { "text": "string", "model": "string" }

`POST /security/cost/calculate`¶

Calculate token cost for a given model.

Body: { "text": "string", "model": "string" }

`GET /security/models`¶

List supported models with token pricing.

Import Jobs¶

Prefix: /import-jobs

`POST /import-jobs`¶

Upload JSON/JSONL file for background processing (max 100MB).

Response: 202

`GET /import-jobs`¶

List import jobs with pagination.

`GET /import-jobs/{import_job_id}`¶

Get import job status.

`GET /import-jobs/{import_job_id}/results`¶

Get import results and error details.

`DELETE /import-jobs/{import_job_id}`¶

Delete an import job.

Metrics¶

`GET /metrics`¶

Prometheus-format metrics export (text/plain).

`GET /metrics/json`¶

JSON metrics export.

`POST /metrics/datadog/flush`¶

Flush metrics to Datadog.

`GET /metrics/datadog/dashboard`¶

Get Datadog dashboard configuration JSON.

Billing¶

`GET /billing/plans`¶

List available pricing plans (public).

`POST /billing/checkout`¶

Create a Stripe Checkout session.

`GET /billing/portal`¶

Get Stripe Customer Portal URL.

`GET /billing/status`¶

Get current billing status.

`POST /billing/webhooks/stripe`¶

Handle Stripe webhook events. Requires stripe-signature header.

Benchmarks¶

`GET /benchmarks`¶

Get detection accuracy benchmarks for MAST failure taxonomy (public).

Response: 16 failure modes (F1-F16) with detection rates and tier levels.

Diagnostics¶

`GET /diagnostics/detector-status`¶

Get detector health and readiness status.

Response: Per-detector F1, precision, recall, sample count, tier (production/beta/experimental).

Rate Limiting¶

Global: 100 requests per 60 seconds per IP (configurable via RATE_LIMIT_REQUESTS)
Auth endpoints: 10 requests per 60 seconds per IP
Exempt: /health, /api/v1/health, /, OPTIONS

CORS¶

Allowed methods: GET, POST, PUT, DELETE, OPTIONS
Allowed headers: Authorization, Content-Type, Accept, X-Pisama-API-Key, X-Pisama-Signature, X-Pisama-Timestamp, X-Pisama-Nonce
Credentials: enabled
Max age: 3600s

API Reference¶

Product capability contract¶

Health¶

GET /health¶

GET /api/v1/health¶

Traces¶

POST /traces/ingest¶

GET /traces¶

GET /traces/{trace_id}¶

GET /traces/{trace_id}/states¶

POST /traces/{trace_id}/analyze¶

Conversations¶

POST /conversations/ingest¶

GET /conversations¶

GET /conversations/{conversation_id}¶

GET /conversations/{conversation_id}/turns¶

POST /conversations/{conversation_id}/analyze¶

Detections¶

GET /detections¶

GET /detections/{detection_id}¶

POST /detections/{detection_id}/validate¶

GET /detections/{detection_id}/fixes¶

POST /detections/{detection_id}/fixes/{fix_id}/apply¶

Agents¶

GET /tenants/{tenant_id}/agents¶

Analytics¶

GET /analytics/loops¶

GET /analytics/cost¶

GET /analytics/quality¶

Feedback¶

POST /feedback¶

GET /feedback/stats¶

GET /feedback/recommendations¶

GET /feedback¶

Healing¶

GET /healing¶

POST /healing/trigger/{detection_id}¶

GET /healing/{healing_id}/status¶

GET /healing/{healing_id}/progress¶

POST /healing/{healing_id}/approve¶

POST /healing/{healing_id}/reject¶

POST /healing/{healing_id}/verify¶

POST /healing/{healing_id}/promote¶

POST /healing/{healing_id}/complete¶

POST /healing/{healing_id}/rollback¶

GET /healing/stats¶

Settings¶

GET /settings/thresholds¶

PUT /settings/thresholds¶

DELETE /settings/thresholds¶

GET /settings/thresholds/defaults¶

GET /settings/thresholds/preview¶

Workflow Groups¶

POST /workflow-groups¶

GET /workflow-groups¶

GET /workflow-groups/{group_id}¶

PUT /workflow-groups/{group_id}¶

DELETE /workflow-groups/{group_id}¶

POST /workflow-groups/{group_id}/assign¶

POST /workflow-groups/{group_id}/auto-detect¶

ATIF Analysis¶

POST /atif/analyze¶

n8n Integration¶

POST /n8n/webhook¶

POST /n8n/workflows¶

GET /n8n/workflows¶

POST /n8n/sync¶

GET /n8n/sync/status¶

POST /n8n/discover¶

GET /n8n/stream¶

Dify Integration¶

POST /dify/webhook¶

POST /dify/instances / GET /dify/instances¶

POST /dify/apps / GET /dify/apps¶

GET /dify/stream¶

LangGraph Integration¶

POST /langgraph/webhook¶

POST /langgraph/deployments / GET /langgraph/deployments¶

POST /langgraph/assistants / GET /langgraph/assistants¶

GET /langgraph/stream¶

`GET /health`¶

`GET /api/v1/health`¶

`POST /traces/ingest`¶

`GET /traces`¶

`GET /traces/{trace_id}`¶

`GET /traces/{trace_id}/states`¶

`POST /traces/{trace_id}/analyze`¶

`POST /conversations/ingest`¶

`GET /conversations`¶

`GET /conversations/{conversation_id}`¶

`GET /conversations/{conversation_id}/turns`¶

`POST /conversations/{conversation_id}/analyze`¶

`GET /detections`¶

`GET /detections/{detection_id}`¶

`POST /detections/{detection_id}/validate`¶

`GET /detections/{detection_id}/fixes`¶

`POST /detections/{detection_id}/fixes/{fix_id}/apply`¶

`GET /tenants/{tenant_id}/agents`¶

`GET /analytics/loops`¶

`GET /analytics/cost`¶

`GET /analytics/quality`¶

`POST /feedback`¶

`GET /feedback/stats`¶

`GET /feedback/recommendations`¶

`GET /feedback`¶

`GET /healing`¶

`POST /healing/trigger/{detection_id}`¶

`GET /healing/{healing_id}/status`¶

`GET /healing/{healing_id}/progress`¶

`POST /healing/{healing_id}/approve`¶

`POST /healing/{healing_id}/reject`¶

`POST /healing/{healing_id}/verify`¶

`POST /healing/{healing_id}/promote`¶

`POST /healing/{healing_id}/complete`¶

`POST /healing/{healing_id}/rollback`¶

`GET /healing/stats`¶

`GET /settings/thresholds`¶

`PUT /settings/thresholds`¶

`DELETE /settings/thresholds`¶

`GET /settings/thresholds/defaults`¶

`GET /settings/thresholds/preview`¶

`POST /workflow-groups`¶

`GET /workflow-groups`¶

`GET /workflow-groups/{group_id}`¶

`PUT /workflow-groups/{group_id}`¶

`DELETE /workflow-groups/{group_id}`¶

`POST /workflow-groups/{group_id}/assign`¶

`POST /workflow-groups/{group_id}/auto-detect`¶

`POST /atif/analyze`¶

`POST /n8n/webhook`¶

`POST /n8n/workflows`¶

`GET /n8n/workflows`¶

`POST /n8n/sync`¶

`GET /n8n/sync/status`¶

`POST /n8n/discover`¶

`GET /n8n/stream`¶

`POST /dify/webhook`¶

`POST /dify/instances` / `GET /dify/instances`¶

`POST /dify/apps` / `GET /dify/apps`¶

`GET /dify/stream`¶

`POST /langgraph/webhook`¶

`POST /langgraph/deployments` / `GET /langgraph/deployments`¶

`POST /langgraph/assistants` / `GET /langgraph/assistants`¶

`GET /langgraph/stream`¶

`POST /openclaw/webhook`¶

`POST /openclaw/instances` / `GET /openclaw/instances`¶

`POST /openclaw/agents` / `GET /openclaw/agents`¶

`GET /openclaw/stream`¶

`POST /traces/claude-code/ingest`¶

`POST /security/injection/check`¶

`POST /security/hallucination/check`¶

`POST /security/overflow/check`¶

`POST /security/cost/calculate`¶

`GET /security/models`¶

`POST /import-jobs`¶

`GET /import-jobs`¶

`GET /import-jobs/{import_job_id}`¶

`GET /import-jobs/{import_job_id}/results`¶

`DELETE /import-jobs/{import_job_id}`¶

`GET /metrics`¶