API Reference — Agent Endpoints

All management endpoints require JWT authentication. The execution endpoint uses API key or public access.

Management Endpoints

Base URL: https://api.aerostack.dev/api/agent-endpoints

List Endpoints

GET /api/agent-endpoints
Authorization: Bearer <JWT>

Returns all agent endpoints owned by the authenticated user.

Response (200):

{
  "endpoints": [
    {
      "id": "aep_7f3a2b9c1d4e5f6a8b",
      "owner_id": "usr_abc123",
      "workspace_id": "ws_def456",
      "name": "summarizer",
      "slug": "summarizer",
      "description": "Summarizes text input",
      "agent_type": "extractor",
      "system_prompt": "You are a concise summarizer...",
      "llm_provider": "openai",
      "llm_model": "gpt-4o-mini",
      "max_tokens": 4096,
      "temperature": 0.3,
      "output_format": "text",
      "max_tool_calls": 10,
      "timeout_ms": 30000,
      "enable_streaming": 0,
      "async_mode": 0,
      "auth_mode": "api_key",
      "price_per_run_cents": 0,
      "status": "active",
      "created_at": "2026-03-15T10:00:00Z",
      "updated_at": "2026-03-15T10:00:00Z"
    }
  ]
}

---

Create Endpoint

POST /api/agent-endpoints
Authorization: Bearer <JWT>
Content-Type: application/json

Request Body:

Field	Type	Required	Default	Description
name	string	Yes	—	1-100 characters
workspace_id	string	Yes	—	MCP workspace ID (1-100 chars)
system_prompt	string	Yes	—	Agent instructions (1-10000 chars)
description	string	No	null	Short description (max 500 chars)
slug	string	No	auto from name	URL slug (max 60 chars)
agent_type	string	No	"extractor"	extractor, actor, or pipeline (informational)
llm_provider	string	No	"openai"	openai, anthropic, gemini, groq, workers-ai, custom
llm_model	string	No	"gpt-4o-mini"	Model identifier (max 100 chars)
llm_api_key	string	No	platform key	Your LLM provider API key (stored securely)
max_tokens	integer	No	4096	100-32768
temperature	number	No	0.3	0-2
input_schema	object	No	null	JSON Schema for expected input (informational)
output_schema	object	No	null	JSON Schema for structured output (used with json format)
output_format	string	No	"text"	text, json, or markdown
max_tool_calls	integer	No	10	1-50. Controls max agentic loop iterations
timeout_ms	integer	No	30000	1000-120000 (hard cap at 60000 during execution)
enable_streaming	boolean	No	false	Return SSE stream instead of JSON
async_mode	boolean	No	false	Not yet implemented (returns 501)
auth_mode	string	No	"api_key"	api_key or public
price_per_run_cents	integer	No	0	0-10000. Per-execution charge from owner’s wallet

Response (201):

{
  "endpoint": { "id": "aep_...", "name": "...", "slug": "...", "..." : "..." },
  "api_key": "aek_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "run_url": "/api/run/summarizer"
}

Caution

The api_key is only returned in this response. Store it securely. Use the regenerate-key endpoint if you lose it.

---

Get Endpoint

GET /api/agent-endpoints/:id
Authorization: Bearer <JWT>

Returns a single endpoint. Returns 404 if not found or not owned by the authenticated user.

Response (200):

{
  "endpoint": { "id": "aep_...", "..." : "..." }
}

---

Update Endpoint

PATCH /api/agent-endpoints/:id
Authorization: Bearer <JWT>
Content-Type: application/json

All fields from the create schema are optional. workspace_id cannot be changed after creation.

Request Body (all fields optional):

Field	Type	Description
name	string	1-100 characters
description	string	Max 500 chars
system_prompt	string	1-10000 chars
agent_type	string	extractor, actor, or pipeline
llm_provider	string	Provider enum
llm_model	string	Model identifier
max_tokens	integer	100-32768
temperature	number	0-2
input_schema	object	JSON Schema
output_schema	object	JSON Schema
output_format	string	text, json, or markdown
max_tool_calls	integer	1-50
timeout_ms	integer	1000-120000
enable_streaming	boolean	SSE mode
async_mode	boolean	Not yet implemented
auth_mode	string	api_key or public
price_per_run_cents	integer	0-10000

Response (200):

{
  "endpoint": { "id": "aep_...", "..." : "..." }
}

---

Delete Endpoint

DELETE /api/agent-endpoints/:id
Authorization: Bearer <JWT>

Permanently deletes the endpoint and all its run history.

Response (200):

{
  "deleted": true
}

---

Activate Endpoint

POST /api/agent-endpoints/:id/activate
Authorization: Bearer <JWT>

Sets the endpoint status to active. Only active endpoints can be executed.

Response (200):

{
  "status": "active"
}

---

Regenerate API Key

POST /api/agent-endpoints/:id/regenerate-key
Authorization: Bearer <JWT>

Generates a new API key and invalidates the previous one.

Response (200):

{
  "api_key": "aek_new_key_shown_once"
}

---

List Runs

GET /api/agent-endpoints/:id/runs?limit=50
Authorization: Bearer <JWT>

Query Param	Type	Default	Max
limit	integer	50	100

Response (200):

{
  "runs": [
    {
      "id": "run_8e4f2a1b3c5d7e9f0a",
      "endpoint_id": "aep_7f3a2b9c1d4e5f6a8b",
      "input": "Summarize this...",
      "output": "The article covers...",
      "tool_calls": "[{\"name\":\"search\",\"success\":true}]",
      "tokens_input": 312,
      "tokens_output": 67,
      "cost_cents": 0.08,
      "latency_ms": 1456,
      "status": "success",
      "caller_ip": "203.0.113.42",
      "created_at": "2026-03-15T10:23:45Z"
    }
  ]
}

---

Test Endpoint

POST /api/agent-endpoints/:id/test
Authorization: Bearer <JWT>
Content-Type: application/json

Executes the endpoint using your JWT session (no API key needed). Rate limited to 10 per minute. Logged with status: "test" and caller_ip: "dashboard".

Request Body:

{
  "input": "Your test input here"
}

Response (200):

{
  "output": "Agent response...",
  "usage": {
    "tokens_input": 245,
    "tokens_output": 89,
    "cost_cents": 0.12,
    "latency_ms": 1823
  }
}

---

Templates

List Templates

GET /api/agent-endpoints/templates/list?type=agent

No authentication required.

Query Param	Type	Values
type	string	agent or webhook

Response (200):

{
  "templates": [
    {
      "id": "tpl_invoice_parser",
      "name": "Invoice Parser",
      "description": "Extract structured data from invoice text",
      "type": "agent",
      "category": "extractor",
      "system_prompt": "You are an invoice parser...",
      "suggested_mcps": "[\"storage\"]",
      "input_schema": null,
      "output_schema": "{\"type\":\"object\",\"properties\":{...}}",
      "popularity": 95,
      "created_at": "2026-03-01T00:00:00Z"
    }
  ]
}

Pre-built agent templates include: Invoice Parser, Lead Enricher, Support Ticket Classifier, PR Code Reviewer, Resume Screener, SQL Query Generator, and Email Drafter.

---

Execution Endpoint

Execute Agent

POST /api/run/:slug
Authorization: Bearer <API_KEY>  (or X-API-Key header, or no auth for public)
Content-Type: application/json

Request Body:

{
  "input": "Your input text or prompt"
}

Alternative input fields (all equivalent): message, text, prompt. If none are present, the entire body is stringified.

Maximum request body size: 2 MB.

Response (200) — Sync Mode:

{
  "output": "Agent response text or parsed JSON object",
  "raw_output": "Original LLM text (only present when output is parsed JSON)",
  "tool_calls": [
    {
      "tool": "github_list_issues",
      "success": true,
      "latency_ms": 234
    }
  ],
  "usage": {
    "tokens_input": 1245,
    "tokens_output": 189,
    "cost_cents": 0.34,
    "latency_ms": 2891,
    "iterations": 2
  }
}

Response — Streaming Mode (SSE):

See SSE Streaming for the full event format.

Error Responses:

Status	Body	Condition
400	{"error": "Input required..."}	No input provided
401	{"error": "API key required..."}	Missing API key (api_key mode)
401	{"error": "Invalid API key"}	Wrong API key
403	{"error": "...unsupported auth mode"}	Auth mode not in allowlist
404	{"error": "Agent endpoint not found or not active"}	Invalid slug or inactive
413	{"error": "Request body too large (max 2MB)"}	Body exceeds 2 MB
429	{"error": "Rate limited..."}	Rate limit exceeded
501	{"error": "Async mode is not yet available..."}	async_mode enabled

---

Error Codes Summary

Code	Meaning
400	Validation failed or missing input
401	Authentication failed
403	Unsupported auth mode
404	Not found or not owner
413	Request body too large
429	Rate limited
501	Feature not yet implemented