API Reference

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"
}

⚠️

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

Pricing & Billing Overview