> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usegradient.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> The two Gradient API surfaces, the engine for running agents and the console for tools, MCP, and management, with their shared JSON and auth conventions.

Gradient exposes two HTTP surfaces. Both speak JSON and authenticate with the same organization API key.

## Base URLs

| Surface | Base URL                              | What it serves                                                                |
| ------- | ------------------------------------- | ----------------------------------------------------------------------------- |
| Engine  | `https://api.usegradient.dev`         | Running published agents: the `invoke` route and the lower-level `turn` route |
| Console | `https://console.usegradient.dev/api` | Custom tool invocation, the hosted MCP server, and organization management    |

The engine owns the conversation loop, so anything that *runs* an agent talks to `api.usegradient.dev`. Everything else (invoking a deployed tool, driving the builder over MCP, reading management resources) talks to the console.

## Conventions

* **Authentication** is an `Authorization: Bearer` header carrying an organization API key. See [Authentication](/api/authentication).
* **Responses are JSON.** Console endpoints wrap results as `{ "ok": true, ... }` and errors as `{ "ok": false, "error": "..." }`. Engine endpoints return the agent payload directly, and `{ "error": "..." }` on failure.
* **Request bodies** are JSON, with one exception: the engine `invoke` route takes the user message as `text/plain`.
* **Errors** use standard HTTP status codes: `401` unauthenticated, `403` missing scope, `400` bad request, `404` not found, `402` when billing blocks the request.

## Test your key

A quick unauthenticated-to-authenticated check is the console `whoami` route, which needs no scope:

```bash theme={null}
curl https://console.usegradient.dev/api/v1/whoami \
  -H "authorization: Bearer $GRADIENT_API_KEY"
```

## Endpoints

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    API keys, the Bearer header, and scopes.
  </Card>

  <Card title="Invoke a published agent" icon="bolt" href="/api/agents/invoke">
    One request in, the agent's reply out.
  </Card>

  <Card title="Turn (low-level)" icon="arrows-rotate" href="/api/agents/turn">
    Carry your own transcript across a conversation.
  </Card>

  <Card title="Invoke a custom tool" icon="wrench" href="/api/tools/invoke">
    Call a deployed handler and get its JSON back.
  </Card>

  <Card title="Hosted MCP" icon="plug" href="/api/mcp">
    Drive your whole organization from an MCP client.
  </Card>
</CardGroup>