Documentation Index
Fetch the complete documentation index at: https://docs.pikarc.dev/llms.txt
Use this file to discover all available pages before exploring further.
Start Run
This is the primary SDK entry point. The SDK calls this automatically when you use guard.run().
Request Body
{
"user_id": "alice",
"metadata": { "agent": "support-bot" }
}
| Field | Type | Required | Description |
|---|
user_id | string | Yes | SDK user identifier |
metadata | object | null | No | Arbitrary metadata attached to the run |
Response 201
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "RUNNING",
"decision": {
"outcome": "ALLOW",
"reason": null
}
}
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "BLOCKED",
"decision": {
"outcome": "DENY",
"reason": "KILL_SWITCH_ACTIVE"
}
}
End Run
POST /v1/runs/{run_id}/end
guard.run() context.
Auth: API Key
Request Body
{
"status": "COMPLETED"
}
| Field | Type | Required | Description |
|---|
status | string | Yes | "COMPLETED" or "FAILED" |
Response 200
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "COMPLETED",
"ended_at": "2025-01-15T10:30:00Z"
}
Create Step
POST /v1/runs/{run_id}/steps
model_call() or tool_call().
Auth: API Key
Request Body
{
"type": "MODEL_CALL",
"sequence": 1,
"model": "gpt-4o",
"tool_name": null,
"input_data": { "messages": [{ "role": "user", "content": "Hello" }] }
}
| Field | Type | Required | Description |
|---|
type | string | Yes | Step type: INPUT, MODEL_CALL, TOOL_CALL, OUTPUT, REASONING, SYSTEM |
sequence | integer | Yes | Step order within the run (1-indexed) |
model | string | null | No | Model identifier (for MODEL_CALL steps) |
tool_name | string | null | No | Tool identifier (for TOOL_CALL steps) |
input_data | object | null | No | Input payload for audit |
Response 201
{
"id": "660e8400-e29b-41d4-a716-446655440000",
"status": "ALLOWED",
"decision": {
"outcome": "ALLOW",
"reason": null
}
}
Update Step
PATCH /v1/runs/{run_id}/steps/{step_id}
fn() completes. Token counts trigger cost calculation.
Auth: API Key
Request Body
{
"status": "COMPLETED",
"duration_ms": 1200,
"prompt_tokens": 500,
"completion_tokens": 100
}
| Field | Type | Required | Description |
|---|
status | string | Yes | "COMPLETED" or "FAILED" |
duration_ms | integer | null | No | Execution time in milliseconds |
prompt_tokens | integer | null | No | Input tokens consumed |
completion_tokens | integer | null | No | Output tokens consumed |
Response 200
{
"id": "660e8400-e29b-41d4-a716-446655440000",
"status": "COMPLETED"
}
List Runs
Lists runs with optional filtering and pagination.
Auth: JWT or API Key
Query Parameters
| Parameter | Type | Default | Description |
|---|
status | string | null | null | Filter by status: RUNNING, COMPLETED, FAILED, BLOCKED |
user_id | string | null | null | Filter by SDK user ID |
page | integer | 1 | Page number (1-indexed) |
per_page | integer | 50 | Items per page (max 100) |
Response 200
{
"items": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"user_id": "alice",
"status": "COMPLETED",
"started_at": "2025-01-15T10:00:00Z",
"ended_at": "2025-01-15T10:30:00Z",
"step_count": 3,
"total_tokens": 1500,
"total_cost_usd": 0.0045
}
],
"total": 142,
"page": 1,
"per_page": 50
}
Get Run Detail
Returns the full run with its step timeline, tokens, and costs.
Auth: JWT or API Key
Response 200
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"user_id": "alice",
"status": "COMPLETED",
"metadata": { "agent": "support-bot" },
"started_at": "2025-01-15T10:00:00Z",
"ended_at": "2025-01-15T10:30:00Z",
"total_tokens": 1500,
"total_cost_usd": 0.0045,
"duration_ms": 1800000,
"steps": [
{
"id": "660e8400-e29b-41d4-a716-446655440000",
"type": "MODEL_CALL",
"status": "COMPLETED",
"sequence": 1,
"model": "gpt-4o",
"tool_name": null,
"prompt_tokens": 500,
"completion_tokens": 100,
"cost_usd": 0.00225,
"duration_ms": 1200,
"input_data": null,
"output_data": null,
"decision": {
"outcome": "ALLOW",
"reason": null
},
"created_at": "2025-01-15T10:00:01Z"
}
]
}
