Skip to main content
An endpoint implementation sends each tool call to your own service, so the model reads real outputs from a real system. This page is for the developer who builds that service. It describes what Oumi sends for each call and how Oumi reads your response. To create the implementation in Oumi, see Tool implementations.

​
REQUESTS

Oumi sends one request per tool call to your endpointUrl. With the HTTP protocol, each request carries two headers: POST, PUT, and PATCH send the tool arguments as the JSON request body. GET and DELETE send them as query parameters. With GET or DELETE, every argument must be a scalar or an array of scalars, and no argument can share a name with a query parameter already in endpointUrl. Oumi repeats the key once for each item in an array and leaves out an argument that is null or an empty array. Oumi rejects an implementation whose tool has parameters that cannot be sent this way. If you set a credential, Oumi sends it in one header. A bearer credential is sent as Authorization: <scheme> <token>. An API key credential is sent on its own in the header you name.

​
RESPONSES

Oumi reads the whole response body as the tool’s output, so return JSON that matches the tool’s output schema. If your service wraps its answer in an envelope, declare that envelope as the tool’s output schema. An empty body, such as a 204 response, is a null output. How Oumi treats the status code:
  • 2xx: the body is the tool’s output.
  • 4xx, except 408 and 429: the tool refused the call. The model reads the status and the first 200 characters of the body as the tool’s answer, so return a short, readable reason.
  • 408, 429, 5xx, timeouts, and unreachable hosts: the endpoint failed to answer. During a job, the model reads a fixed message that says the tool could not be run.
A response that is not valid JSON, is larger than 1 MiB, or does not match the tool’s output schema also counts as a failure. Oumi does not follow redirects.

​
MCP

With the MCP protocol, Oumi sends each call as one stateless JSON-RPC tools/call request over Streamable HTTP, with no initialize handshake. The request names the tool by its tool name, carries the arguments, and puts the session ID under _meta as ai.oumi/sessionId. Your server may answer with JSON or with a server-sent event stream.
  • If the result includes structuredContent, Oumi uses it as the tool’s output. Otherwise, Oumi joins the result’s text content blocks into a string.
  • A result with isError: true is a refusal. The model reads its text content as the tool’s answer.
  • A JSON-RPC error or a non-2xx status is a failure, not a refusal.

​
ADDRESS AND TIMEOUT RULES

  • The URL must use HTTPS, and its host must resolve to a public address. Oumi checks this when you create the implementation.
  • timeoutSeconds sets how long Oumi waits for one call, from 1 to 120 seconds. The default is 30.

​
CREDENTIALS

If your service needs a credential, Oumi sends it in one header with every call:
  • Bearer token: Oumi sends Authorization: <scheme> <token>. The scheme defaults to Bearer.
  • API key header: Oumi sends the token on its own in the header you name.
Set the credential when you create the implementation, or later with Set credential on the implementation’s page. Calls are sent without authentication until a credential is set. To replace the token, click Rotate credential. The new token uses the same header as the old one. New jobs use the new token, and running jobs keep the one they started with. A credential can’t be removed after it is set. Oumi never returns the full token after you save it.

​
TEST YOUR ENDPOINT

Test the implementation from its Test card before you use it in a job. Each test sends one real call to your service, so a call that changes data takes effect. A 4xx response appears as a refusal, with the status and the start of your response body. See Test an implementation.