Quick Start: Agent Endpoints

Create your first AI agent endpoint and call it from the command line. This takes about 3 minutes.

You need an Aerostack account and at least one MCP workspace with a connected server. If you have not set up a workspace yet, see MCP Workspaces.

Create the Agent Endpoint

From the Dashboard:

Log in to the Aerostack Dashboard
Navigate to Agent Endpoints in the sidebar
Click Create Endpoint
Fill in the form:
- Name: summarizer
- System Prompt: You are a concise summarizer. Given any text, produce a clear 2-3 sentence summary that captures the key points.
- Workspace: Select your workspace
- LLM Model: gpt-4o-mini (default)
- Output Format: text
Click Create

You will see your API key and run URL. Copy the API key now — it is only shown once.

Or via the API:

curl -X POST https://api.aerostack.dev/api/agent-endpoints \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "summarizer",
    "workspace_id": "ws_your_workspace_id",
    "system_prompt": "You are a concise summarizer. Given any text, produce a clear 2-3 sentence summary that captures the key points.",
    "llm_model": "gpt-4o-mini",
    "output_format": "text"
  }'

Response:

{
  "endpoint": {
    "id": "aep_7f3a2b9c1d4e5f6a8b",
    "name": "summarizer",
    "slug": "summarizer",
    "status": "active",
    "auth_mode": "api_key",
    "llm_provider": "openai",
    "llm_model": "gpt-4o-mini",
    "output_format": "text",
    "max_tool_calls": 10,
    "timeout_ms": 30000,
    "temperature": 0.3,
    "max_tokens": 4096,
    "price_per_run_cents": 0
  },
  "api_key": "aek_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "run_url": "/api/run/summarizer"
}

⚠️

Save the api_key value immediately. It is only returned once during creation. If you lose it, use the regenerate-key endpoint to get a new one (which invalidates the old key).

Call Your Agent

Use the run_url and api_key from the previous step:

curl -X POST https://api.aerostack.dev/api/run/summarizer \
  -H "Authorization: Bearer aek_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Aerostack is a B2B2X API platform that serves as a headless backend builder for developers. It allows teams to create, configure, and monetize backend APIs with built-in CMS, authentication, e-commerce, AI capabilities, real-time features, and an API gateway. The entire platform runs on Cloudflare edge infrastructure for low-latency global performance. Developers can deploy functions, connect MCP servers for tool access, and publish APIs to a community marketplace."
  }'

Response:

{
  "output": "Aerostack is a developer-focused API platform that combines CMS, auth, AI, real-time, and API gateway features into a single headless backend builder. Built on Cloudflare's edge network, it enables teams to create, monetize, and deploy backend APIs with low-latency global performance, including MCP tool integration and a community marketplace.",
  "usage": {
    "tokens_input": 312,
    "tokens_output": 67,
    "cost_cents": 0.08,
    "latency_ms": 1456,
    "iterations": 1
  }
}

View Execution History

Check the runs for your endpoint in the dashboard, or via the API:

curl https://api.aerostack.dev/api/agent-endpoints/aep_7f3a2b9c1d4e5f6a8b/runs \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "runs": [
    {
      "id": "run_8e4f2a1b3c5d7e9f0a",
      "endpoint_id": "aep_7f3a2b9c1d4e5f6a8b",
      "input": "Aerostack is a B2B2X API platform...",
      "output": "Aerostack is a developer-focused API platform...",
      "tokens_input": 312,
      "tokens_output": 67,
      "cost_cents": 0.08,
      "latency_ms": 1456,
      "status": "success",
      "created_at": "2026-03-15T10:23:45Z"
    }
  ]
}

Test from the Dashboard

You can also test your endpoint directly from the dashboard without using the API key. The dashboard uses your JWT session for authentication:

curl -X POST https://api.aerostack.dev/api/agent-endpoints/aep_7f3a2b9c1d4e5f6a8b/test \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": "Test input text here"}'

Test runs are rate limited to 10 per minute per endpoint and logged with status: "test" in the run history.

Input Field Flexibility

The execution endpoint accepts input in several field names for convenience:

{"input": "your text"}
{"message": "your text"}
{"text": "your text"}
{"prompt": "your text"}

All are equivalent. If none of these fields are present, the entire request body is stringified and used as input.

What Happens Behind the Scenes

When you call /api/run/:slug, the platform:

Authenticates — Checks the API key or allows public access
Rate limits — 60 requests per minute per endpoint; 20 per minute per IP for public endpoints
Loads MCP tools — Loads all available tool definitions from the workspace
Runs the agent — Sends your input + system prompt to the LLM with available tools
Executes tool calls — If the LLM requests tools, executes them and feeds results back
Repeats — The loop continues until the LLM produces a final response or hits the max_tool_calls limit
Charges — If price_per_run_cents > 0, deducts from the owner’s wallet
Logs — Records the run with input, output, token counts, cost, and latency

Next Steps

SSE Streaming — Get real-time progress events during execution
Output Formats — Return structured JSON instead of text
Pricing — Set per-run charges and understand cost breakdown
API Reference — Full endpoint and schema documentation

Overview SSE Streaming