# Run with the API

> Run your 10xGraph agent as an HTTP API: scaffold a project with 10xgraph init, start the server with 10xgraph api, and call your agent over HTTP.

Source: https://10xgraph.com/docs/beginner/run-with-api
Last updated: 2026-07-21

Running the agent as a script is fine for testing, but production use requires an HTTP API. The `agentflow-cli` package provides two commands that handle this: `agentflow init` scaffolds the project and `agentflow api` starts the server.

## Install the CLI

```bash
pip install 10xscale-agentflow-cli
```

## Scaffold the project

Create a new folder for your API project, then run:

```bash
mkdir my-agent-api && cd my-agent-api
agentflow init
```

This creates:

```
my-agent-api/
  10xgraph.json      # configuration file
  graph/
    __init__.py
    react.py          # default graph module
```

The default `10xgraph.json` points to `graph.react:app`:

```json
{
  "agent": "graph.react:app"
}
```

This means: find the variable `app` in the `graph/react.py` module and use it as the compiled graph.

## Add your graph

Replace `graph/react.py` with the agent you built in the previous pages:

```python
from tenxgraph.core.graph import Agent, StateGraph, ToolNode
from tenxgraph.core.state import AgentState
from tenxgraph.storage.checkpointer import InMemoryCheckpointer
from tenxgraph.utils import END

def get_weather(location: str) -> str:
    """Get the current weather for a specific location."""
    return f"The weather in {location} is sunny and 22°C."

tool_node = ToolNode([get_weather])
checkpointer = InMemoryCheckpointer()

agent = Agent(
    model="google/gemini-2.5-flash",
    system_prompt=[
        {
            "role": "system",
            "content": "You are a helpful assistant. Use tools when you need specific information.",
        }
    ],
    tool_node="TOOL",
)

graph = StateGraph(AgentState)
graph.add_node("MAIN", agent)
graph.add_node("TOOL", tool_node)

def route(state: AgentState) -> str:
    from tenxgraph.utils import END
    if not state.context:
        return END
    last = state.context[-1]
    if hasattr(last, "tools_calls") and last.tools_calls and last.role == "assistant":
        return "TOOL"
    if last.role == "tool":
        return "MAIN"
    return END

graph.add_conditional_edges("MAIN", route, {"TOOL": "TOOL", END: END})
graph.add_edge("TOOL", "MAIN")
graph.set_entry_point("MAIN")

app = graph.compile(checkpointer=checkpointer)
```

## Start the API server

From the folder that contains `10xgraph.json`:

```bash
agentflow api --host 127.0.0.1 --port 8000
```

Expected output:

```text
INFO: AgentFlow API starting on http://127.0.0.1:8000
INFO: Uvicorn running on http://127.0.0.1:8000
```

## Test it

In a second terminal, send a request with `curl`:

```bash
curl -X POST http://127.0.0.1:8000/v1/graph/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "What is the weather in Tokyo?"}],
    "config": {"thread_id": "api-demo-1"}
  }'
```

Expected response (trimmed):

```json
{
  "messages": [
    {"role": "user", "content": "What is the weather in Tokyo?"},
    {"role": "assistant", "content": "The weather in Tokyo is sunny and 22°C."}
  ]
}
```

## What happened

```mermaid
flowchart LR
  Curl[curl POST] --> API[FastAPI server]
  API --> Config[10xgraph.json]
  Config --> Module[graph/react.py]
  Module --> App[compiled app]
  App --> Graph[nodes + checkpointer]
  Graph --> Response[JSON messages]
```

The CLI started a FastAPI server. The server loaded your graph module based on `10xgraph.json`, compiled it once at startup, and now handles each HTTP request by invoking the graph.

## Available endpoints

| Endpoint | Description |
| --- | --- |
| `POST /v1/graph/invoke` | Invoke the graph and return all messages |
| `POST /v1/graph/stream` | Stream messages as server-sent events |
| `GET /v1/graph/threads/{thread_id}` | Get thread state |
| `GET /health` | Health check |

## What you learned

- `agentflow init` scaffolds a project with `10xgraph.json` and a graph module.
- `agentflow api` starts a FastAPI server that loads your compiled graph.
- The `agent` field in `10xgraph.json` uses `module.path:variable` notation.
- The API exposes `/v1/graph/invoke` and `/v1/graph/stream`.

## Next step

Use the hosted playground to inspect requests without writing client code — [Test with the playground](/docs/beginner/test-with-playground).