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

​
Base URLs

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

​
Endpoints

Authentication

API keys, the Bearer header, and scopes.

Invoke a published agent

One request in, the agent’s reply out.

Turn (low-level)

Carry your own transcript across a conversation.

Invoke a custom tool

Call a deployed handler and get its JSON back.

Hosted MCP

Drive your whole organization from an MCP client.