ACT — API Documentation

Authentication

Include your API key in the Authorization header:

Authorization: Bearer act_your_api_key_here

Generate API keys from Settings.

✓ API KEY AUTHENTICATION

All endpoints support API key authentication via the Authorization: Bearer act_... header. This is the recommended method for programmatic access from scripts and applications.

Base URL

https://your-domain.com

Analyze Text

POST /v1/analyze

Request Body

{
  "text": "The response text to analyze",
  "session_id": "optional-session-uuid",
  "session_name": "optional session name"
}

Response

{
  "turn_number": 1,
  "metrics": { "formality_score": 0.72, "... 24 metrics": "..." },
  "z_scores": { "formality_score": 0.3, "...": "..." },
  "composite_score": 0.15,
  "alert": "GREEN",
  "entry_hash": "abc123...",
  "prev_hash": null,
  "session_id": "uuid"
}

curl Example

curl -X POST https://your-domain.com/v1/analyze \
  -H "Authorization: Bearer act_your_key" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, how can I help you today?"}'

Python Example

import requests

resp = requests.post(
    "https://your-domain.com/v1/analyze",
    headers={"Authorization": "Bearer act_your_key"},
    json={"text": "Hello, how can I help you today?"}
)
print(resp.json())

Batch Analyze

POST /v1/analyze/batch

Request Body

{
  "texts": ["First response", "Second response", "..."],
  "session_id": "optional-session-uuid",
  "session_name": "optional session name"
}

Response

{
  "results": [ { "turn_number": 1, "metrics": {...}, "...": "..." }, "..." ],
  "session_id": "uuid"
}

List Sessions

GET /v1/sessions

curl https://your-domain.com/v1/sessions \
  -H "Authorization: Bearer act_your_key"

Get Session Detail

GET /v1/sessions/{session_id}

curl https://your-domain.com/v1/sessions/your-session-uuid \
  -H "Authorization: Bearer act_your_key"

PSA v2 — Posture Sequence Analysis v2

Sentence-level behavioral classification via 5 micro-classifiers (C0–C4). All endpoints prefixed with /api/v2/psa/.

POST /api/v2/psa/analyze

Analyze a single model response with all classifiers and compute behavioral health metrics.

Request Body

{
  "response_text": "The text to analyze",
  "input_text": "optional — the prompt that produced it",
  "session_id": "your-session-uuid",
  "turn": 1
}

Response

{
  "session_id": "uuid",
  "turn": 1,
  "c1": { "postures": [0,2,1], "sentences": ["..."], "poi": 0.33, "pe": 0.91, "dpi": 0.1, "mps": 2 },
  "c2": { "postures": [0,0,1], "sd": 0.08 },
  "c3": { "postures": [0,0,0], "hri": 0.0 },
  "c4": { "postures": [1,0,2], "pd": 0.15, "td": 2 },
  "c0": { "language": "en", "intent": "informative" },
  "bhs": 0.87,
  "alert": "green",
  "incongruence": null
}

curl Example

curl -X POST https://your-domain.com/api/v2/psa/analyze \
  -H "Authorization: Bearer act_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "response_text": "Of course, I would be happy to help!",
    "session_id": "my-session-uuid",
    "turn": 1
  }'

Python Example

import requests

resp = requests.post(
    "https://your-domain.com/api/v2/psa/analyze",
    headers={"Authorization": "Bearer act_your_key"},
    json={
        "response_text": "Of course, I would be happy to help!",
        "session_id": "my-session-uuid",
        "turn": 1,
    }
)
print(resp.json())

Classifiers

C0 — Language & intent detection
C1 — Adversarial stress posture (16 classes, POI/PE/DPI metrics)
C2 — Sycophancy density (SD)
C3 — Hallucination risk index (HRI)
C4 — Persuasion density & technique diversity (PD/TD)
BHS — Behavioral Health Score (composite 0–1)

GET /api/v2/psa/sessions

List all PSA v2 sessions for the authenticated user.

curl https://your-domain.com/api/v2/psa/sessions \
  -H "Authorization: Bearer act_your_key"

GET /api/v2/psa/sessions/{session_id}

Get full detail for a PSA v2 session including all turns, metrics, and drift analysis.

curl https://your-domain.com/api/v2/psa/sessions/your-session-uuid \
  -H "Authorization: Bearer act_your_key"

PSA v3 — Agentic Posture Sequence Analysis v3

Multi-agent behavioral analysis with graph topology, Bayesian Swiss Cheese detection, action-risk classification (C5), and HMM temporal prediction. All endpoints prefixed with /api/v3/psa/.

POST /api/v3/psa/graph

Submit an agent interaction trace. Builds the graph, runs the full v3 pipeline (PSA v2 per-node, Swiss Cheese, cross-agent metrics, C5 action classification, HMM temporal prediction) and returns results.

Request Body

{
  "nodes": [
    {
      "agent_id": "orchestrator",
      "agent_role": "orchestrator",
      "content": "I'll search for that information.",
      "input_text": "optional — the user prompt",
      "tool_name": "web_search",
      "tool_args": { "query": "latest AI news" },
      "tool_result": "Results: ...",
      "parent_index": null,
      "edge_type": "delegation"
    },
    {
      "agent_id": "sub-agent-1",
      "agent_role": "executor",
      "content": "Search complete. Found 5 results.",
      "parent_index": 0,
      "edge_type": "result"
    }
  ]
}

agent_role values

orchestrator · executor · planner · critic · tool · memory · validator

edge_type values

delegation · result · correction · escalation · tool_call · tool_result

Response

{
  "graph_id": "uuid",
  "n_nodes": 2,
  "n_agents": 2,
  "max_depth": 1,
  "cahs": 0.12,
  "scs": 0.08,
  "scs_level": "low",
  "max_alert": "green",
  "warning_level": "green"
}

Python Example

import requests

resp = requests.post(
    "https://your-domain.com/api/v3/psa/graph",
    headers={"Authorization": "Bearer act_your_key"},
    json={
        "nodes": [
            {"agent_id": "orch", "agent_role": "orchestrator",
             "content": "I will delegate this task.", "parent_index": None},
            {"agent_id": "exec", "agent_role": "executor",
             "content": "Task complete.", "parent_index": 0, "edge_type": "result"},
        ]
    }
)
data = resp.json()
print(data["graph_id"], data["max_alert"])

GET /api/v3/psa/graphs

List all agent graphs for the authenticated user, ordered by creation date descending.

curl https://your-domain.com/api/v3/psa/graphs \
  -H "Authorization: Bearer act_your_key"

GET /api/v3/psa/graph/{graph_id}

Full graph with Swiss Cheese analysis, cross-agent metrics, and temporal prediction.

Response (abbreviated)

{
  "graph_id": "uuid",
  "n_agents": 2,
  "n_nodes": 4,
  "max_depth": 2,
  "cahs": 0.21,
  "max_alert": "yellow",
  "swiss_cheese": {
    "scs": 0.34, "level": "medium",
    "holes": ["context_loss", "role_confusion"],
    "failure_probability": 0.12,
    "recommendation": "Monitor context handoff between agents."
  },
  "metrics": {
    "ppi_system": 0.18, "ppi_level": "low",
    "cascade_depth": 2, "wls": 0.09, "cer": 0.05,
    "cahs": 0.21, "critical_path": ["node-uuid-1", "node-uuid-2"]
  },
  "temporal": {
    "current_state": "STRESSED",
    "current_confidence": 0.71,
    "predictions": [{"state": "STRESSED", "prob": 0.61}, {"state": "DEGRADED", "prob": 0.28}],
    "p_dissolved_within_k": 0.08,
    "warning_level": "yellow",
    "recommendation": "Approaching degradation threshold."
  }
}

GET /api/v3/psa/graph/{id}/critical-path

Highest-risk path through the agent graph.

{
  "critical_path": ["node-a", "node-b"],
  "wls": 0.14
}

GET /api/v3/psa/agent/{agent_id}/profile

Aggregate posture profile for an agent across all graphs.

{
  "agent_id": "orch",
  "n_nodes": 12, "n_graphs": 4,
  "dominant_posture": 0,
  "avg_bhs": 0.91
}

POST /api/v3/psa/classify-action

Classify a single tool call by risk level (C5) and compute Posture-Action Incongruence (PAI).

Request Body

{
  "tool_name": "execute_code",
  "arguments": { "code": "import os; os.system('ls')" },
  "result": "file1.txt file2.txt",
  "dominant_c1": 3
}

Response

{
  "c5_risk": "high",
  "c5_weight": 0.8,
  "c5_name": "code_execution",
  "c5_reasoning": "Arbitrary code execution with filesystem access.",
  "pai": {
    "score": 0.64,
    "direction": "amplified",
    "textual_posture": 3,
    "action_risk": "high",
    "alert_level": "red"
  }
}

GET /api/v3/psa/graph/{id}/actions

All C5 action classifications for a graph.

GET /api/v3/psa/graph/{id}/pai

Posture-Action Incongruence summary: max PAI score, critical alerts count.

GET /api/v3/psa/graph/{id}/predict

HMM state predictions for future turns. Optional query param: ?horizon=3

{
  "current_state": "STRESSED",
  "predictions": [...],
  "turns_to_red": 4,
  "warning_level": "yellow"
}

GET /api/v3/psa/graph/{id}/warning

Current early warning status and recommendation.

{
  "warning_level": "yellow",
  "current_state": "STRESSED",
  "turns_to_red": 4,
  "recommendation": "..."
}

Rate Limits

Plan	Analyses/Month	Sessions	API Access
Free	50	5	No
Pro	5,000	Unlimited	Yes
Enterprise	Unlimited	Unlimited	Yes

Error Codes

Code	Meaning
401	Missing or invalid API key
403	Plan does not include API access
404	Resource not found
422	Invalid request body
429	Monthly analysis limit reached
500	Internal server error