Quick Start: Agent Endpoints

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

Note

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.

1. Create the Agent Endpoint

   From the Dashboard:

   1. Log in to the Aerostack Dashboard
   2. Navigate to Agent Endpoints in the sidebar
   3. Click Create Endpoint
   4. 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
   5. 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"
   }

   Caution

   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).

2. 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
     }
   }

3. 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:

1. Authenticates — Checks the API key or allows public access
2. Rate limits — 60 requests per minute per endpoint; 20 per minute per IP for public endpoints
3. Loads MCP tools — Loads all available tool definitions from the workspace
4. Runs the agent — Sends your input + system prompt to the LLM with available tools
5. Executes tool calls — If the LLM requests tools, executes them and feeds results back
6. Repeats — The loop continues until the LLM produces a final response or hits the max_tool_calls limit
7. Charges — If price_per_run_cents > 0, deducts from the owner’s wallet
8. 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