API Reference

Complete reference for SystemPrompt HTTP API endpoints.

Base URL

http://localhost:3000  # Local
https://your-tenant.systemprompt.io  # Cloud

Authentication

Most endpoints require authentication via Bearer token:

curl -H "Authorization: Bearer <token>" https://api.example.com/endpoint

Get Access Token

# OAuth2 client credentials
curl -X POST https://api.example.com/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=<client_id>" \
  -d "client_secret=<client_secret>"

---

Discovery Endpoints

Health Check

GET /health

Response:

{
  "status": "healthy",
  "version": "0.0.14",
  "uptime_seconds": 3600
}

Default Agent Card

GET /.well-known/agent-card.json

Response: A2A agent card for default agent.

List Agent Cards

GET /.well-known/agent-cards

Response: Array of all published agent cards.

Specific Agent Card

GET /.well-known/agent-cards/{agent_name}

---

Agent Registry

List Agents

GET /api/v1/agents/registry
Authorization: Bearer <token>

Response:

{
  "agents": [
    {
      "name": "welcome",
      "status": "running",
      "endpoint": "/api/v1/agents/welcome",
      "capabilities": ["chat", "tools"]
    }
  ]
}

Get Agent

GET /api/v1/agents/{agent_name}
Authorization: Bearer <token>

Send Message to Agent

POST /api/v1/agents/{agent_name}/messages
Authorization: Bearer <token>
Content-Type: application/json

{
  "content": "Hello, agent!",
  "context_id": "optional-context-id"
}

Response:

{
  "id": "msg_123",
  "content": "Hello! How can I help you?",
  "agent": "welcome",
  "timestamp": "2025-01-27T12:00:00Z"
}

---

MCP Registry

List MCP Servers

GET /api/v1/mcp/registry
Authorization: Bearer <token>

Response:

{
  "servers": [
    {
      "name": "content-manager",
      "endpoint": "/api/v1/mcp/content-manager/mcp",
      "transport": "streamable-http",
      "tools": ["create_content", "list_content"]
    }
  ]
}

MCP Endpoint

POST /api/v1/mcp/{server_name}/mcp
Authorization: Bearer <token>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}

---

Users

List Users

GET /api/v1/users
Authorization: Bearer <token>

Query Parameters:

Param	Type	Description
limit	int	Max results (default: 50)
offset	int	Pagination offset

Get User

GET /api/v1/users/{user_id}
Authorization: Bearer <token>

Create User

POST /api/v1/users
Authorization: Bearer <token>
Content-Type: application/json

{
  "email": "user@example.com",
  "name": "User Name"
}

Update User

PUT /api/v1/users/{user_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Updated Name"
}

Delete User

DELETE /api/v1/users/{user_id}
Authorization: Bearer <token>

---

Content

List Content

GET /api/v1/content
Authorization: Bearer <token>

Query Parameters:

Param	Type	Description
source	string	Filter by source (blog, docs)
limit	int	Max results
offset	int	Pagination offset
public	bool	Filter by visibility

Get Content

GET /api/v1/content/{content_id}
Authorization: Bearer <token>

Search Content

GET /api/v1/content/search
Authorization: Bearer <token>

Query Parameters:

Param	Type	Description
q	string	Search query
source	string	Filter by source

Create Content

POST /api/v1/content
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "New Article",
  "slug": "new-article",
  "content": "Article content...",
  "source": "blog",
  "kind": "article",
  "public": true
}

---

Files

Upload File

POST /api/v1/files
Authorization: Bearer <token>
Content-Type: multipart/form-data

file=@/path/to/file.png
path=/images/uploads/

Response:

{
  "id": "file_123",
  "path": "/images/uploads/file.png",
  "size": 12345,
  "content_type": "image/png"
}

Get File

GET /api/v1/files/{file_id}
Authorization: Bearer <token>

Delete File

DELETE /api/v1/files/{file_id}
Authorization: Bearer <token>

---

Analytics

Get Metrics

GET /api/v1/analytics/metrics
Authorization: Bearer <token>

Query Parameters:

Param	Type	Description
from	date	Start date
to	date	End date
metric	string	Metric name

---

OAuth

Authorization

GET /oauth/authorize

Query Parameters:

Param	Type	Description
client_id	string	OAuth client ID
redirect_uri	string	Callback URL
response_type	string	code
scope	string	Requested scopes
state	string	CSRF token

Token

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
code=<auth_code>
client_id=<client_id>
client_secret=<client_secret>
redirect_uri=<redirect_uri>

Response:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "..."
}

---

Error Responses

All errors follow this format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": {
      "field": "email",
      "reason": "Invalid format"
    }
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
429	Rate Limited
500	Server Error

Error Codes

Code	Description
VALIDATION_ERROR	Invalid input
NOT_FOUND	Resource not found
UNAUTHORIZED	Authentication required
FORBIDDEN	Insufficient permissions
RATE_LIMITED	Too many requests

---

Rate Limits

Endpoint Type	Limit
Public	100 req/min
Authenticated	1000 req/min
Agent Messages	60 req/min

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1706360400