API Reference
Complete reference for the runpiper HTTP API.
Base URL
All API requests should be made to:
https://api.runpiper.dev/v1
For self-hosted instances:
http://your-instance.com:8080/v1
Authentication
Include your API key in the Authorization header:
Authorization: Bearer rp_xxx
API keys can be obtained from the runpiper Cloud dashboard or self-hosted instance.
Chat Completions
Generate chat completions using LLMs.
Request
POST /v1/chat/completions
Headers:
Authorization: Bearer rp_xxx(required)Content-Type: application/json(required)
Body:
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Model identifier (e.g., anthropic/claude-sonnet) |
messages | array | Yes | Array of message objects |
temperature | number | No | Sampling temperature (0-2) |
max_tokens | number | No | Maximum tokens to generate |
stream | boolean | No | Enable streaming responses |
Example:
{
"model": "anthropic/claude-sonnet",
"messages": [{ "role": "user", "content": "Hello, how are you?" }]
}
Response
{
"id": "chatcmpl_xxx",
"object": "chat.completion",
"created": 1234567890,
"model": "anthropic/claude-sonnet",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "I'm doing well, thank you for asking!"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 10,
"completion_tokens": 15,
"total_tokens": 25
}
}
Tasks
List Tasks
Get a list of all tasks for your organization.
GET /v1/tasks
Headers:
Authorization: Bearer rp_xxx(required)
Response:
{
"tasks": [
{
"id": "task_xxx",
"name": "summarize",
"status": "live",
"created_at": "2025-01-13T10:00:00Z",
"updated_at": "2025-01-13T10:00:00Z"
}
]
}
Get Task
Get details of a specific task.
GET /v1/tasks/:id
Headers:
Authorization: Bearer rp_xxx(required)
Path Parameters:
id- Task ID
Response:
{
"id": "task_xxx",
"name": "summarize",
"status": "live",
"config": {
"model": {
"provider": "anthropic",
"name": "claude-3-haiku"
},
"prompts": {
"system": "Summarize the given text",
"user": "{{input.text}}"
}
},
"created_at": "2025-01-13T10:00:00Z",
"updated_at": "2025-01-13T10:00:00Z"
}
Execute Task
Run a task with input data.
POST /v1/tasks/:name/run
Headers:
Authorization: Bearer rp_xxx(required)Content-Type: application/json(required)
Path Parameters:
name- Task name
Body:
Input data matching the task’s prompt template.
{
"input": {
"text": "Long text to summarize..."
}
}
Response:
{
"id": "run_xxx",
"task_id": "task_xxx",
"task_name": "summarize",
"status": "completed",
"output": "Summarized text...",
"cost_usd": 0.005,
"duration_ms": 1250,
"created_at": "2025-01-13T10:00:00Z",
"completed_at": "2025-01-13T10:00:01Z"
}
Create Task
Create a new task.
POST /v1/tasks
Headers:
Authorization: Bearer rp_xxx(required)Content-Type: application/json(required)
Body:
Task configuration in TOML format.
{
"name": "summarize",
"config": "[task]\nname = \"summarize\"\n\n[model]\nprovider = \"anthropic\"\nname = \"claude-3-haiku\"\n\n[prompts]\nsystem = \"Summarize text\"\nuser = \"{{input.text}}\""
}
Response:
{
"id": "task_xxx",
"name": "summarize",
"status": "preview",
"created_at": "2025-01-13T10:00:00Z"
}
Delete Task
Delete a task.
DELETE /v1/tasks/:id
Headers:
Authorization: Bearer rp_xxx(required)
Path Parameters:
id- Task ID
Response:
{
"deleted": true
}
Runs
Get Run
Get details of a specific task run.
GET /v1/runs/:id
Headers:
Authorization: Bearer rp_xxx(required)
Path Parameters:
id- Run ID
Response:
{
"id": "run_xxx",
"task_id": "task_xxx",
"task_name": "summarize",
"status": "completed",
"input": {
"text": "Long text..."
},
"output": "Summarized text...",
"cost_usd": 0.005,
"duration_ms": 1250,
"tokens": {
"prompt": 100,
"completion": 50,
"total": 150
},
"created_at": "2025-01-13T10:00:00Z",
"completed_at": "2025-01-13T10:00:01Z"
}
List Runs
Get a list of task runs.
GET /v1/runs?task_id=:task_id&limit=20&offset=0
Headers:
Authorization: Bearer rp_xxx(required)
Query Parameters:
task_id(optional) - Filter by task IDlimit(optional, default: 20) - Maximum number of resultsoffset(optional, default: 0) - Number of results to skip
Response:
{
"runs": [
{
"id": "run_xxx",
"task_id": "task_xxx",
"status": "completed",
"cost_usd": 0.005,
"created_at": "2025-01-13T10:00:00Z"
}
],
"total": 50,
"limit": 20,
"offset": 0
}
Error Responses
All API errors follow this format:
{
"error": {
"type": "authentication_error",
"message": "Invalid API key"
}
}
Common Error Codes
| Status Code | Error Type | Description |
|---|---|---|
| 400 | invalid_request_error | Invalid request parameters |
| 401 | authentication_error | Invalid or missing API key |
| 403 | permission_error | Insufficient permissions |
| 404 | not_found_error | Resource not found |
| 429 | rate_limit_error | Rate limit exceeded |
| 500 | api_error | Internal server error |
Rate Limits
| Plan | Requests per minute |
|---|---|
| Free | 60 |
| Pro | 300 |
| Enterprise | Custom |
Rate limit headers are included in responses:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705123456
Pagination
List endpoints support pagination via limit and offset parameters.
Example:
# Get first 20 results
GET /v1/runs?limit=20&offset=0
# Get next 20 results
GET /v1/runs?limit=20&offset=20
Webhooks
Configure webhooks to receive notifications about task completions.
Create Webhook
POST /v1/webhooks
Headers:
Authorization: Bearer rp_xxx(required)Content-Type: application/json(required)
Body:
{
"url": "https://your-site.com/webhook",
"events": ["task.completed", "task.failed"]
}
Response:
{
"id": "wh_xxx",
"url": "https://your-site.com/webhook",
"events": ["task.completed", "task.failed"],
"secret": "whsec_xxx",
"created_at": "2025-01-13T10:00:00Z"
}
Webhook Payload
When an event triggers, your webhook endpoint receives:
{
"id": "evt_xxx",
"event": "task.completed",
"data": {
"run_id": "run_xxx",
"task_id": "task_xxx",
"status": "completed",
"output": "Result...",
"cost_usd": 0.005
},
"timestamp": "2025-01-13T10:00:00Z"
}
Next Steps
- Tasks: Learn about tasks
- CLI Reference: Complete CLI command documentation
- Self-Hosted Deployment: Deploy your own instance