TOOL IMPLEMENTATION SCHEMA

OVERVIEW

A tool implementation decides how calls to one tool are answered. This page describes the request bodies used to create, update, and test one, and the responses Oumi returns. For a task-oriented introduction, see Tool implementations. All routes are under https://api.oumi.ai/v1/projects/{project_id}/tools/{tool_id}/implementations. Authenticate with the X-API-Key header.

Method	Path	Description
`POST`	`/implementations`	Create an implementation of the tool
`GET`	`/implementations`	List the tool’s implementations
`GET`	`/implementations/{implementation_id}`	Get an implementation
`GET`	`/implementations/{implementation_id}/config`	Get an implementation’s configuration
`PATCH`	`/implementations/{implementation_id}`	Rename an implementation or rotate its credential
`POST`	`/implementations/{implementation_id}:execute`	Run one tool call through an implementation
`DELETE`	`/implementations/{implementation_id}`	Delete an implementation

CREATE REQUEST

{
  "displayName": "Order Lookup",
  "config": {
    "type": "lookup",
    "lookupTable": []
  }
}

Field	Type	Required	Description
displayName	string	✓	Display name, 1 to 128 characters, without `<`, `>`, or `&`
config	object	✓	Implementation configuration; `config.type` selects the shape

config.type accepts lookup, simulated, endpoint, or interactive. The type cannot change after creation.

LOOKUP CONFIG

{
  "type": "lookup",
  "lookupTable": [
    {"input": {"orderId": "A-100"}, "output": {"status": "shipped"}},
    {"input": {"orderId": "A-101"}, "output": {"status": "processing"}}
  ]
}

Field	Type	Required	Description
type	string	✓	Must be `lookup`
lookupTable	object[]	✓	Rows that map tool inputs to outputs

Each lookupTable row contains:

Field	Type	Required	Description
input	object	✓	Tool arguments this row matches
output	any	✓	JSON value returned when a call matches `input`; may be `null`

A call whose arguments match no row is refused. The refusal reaches the model as the tool’s answer.

SIMULATED CONFIG

{
  "type": "simulated",
  "toolPersona": "Return a plausible order status. Use realistic order dates and carriers.",
  "modelIdentifier": {"modelType": "ANTHROPIC_API", "modelName": "claude-sonnet-5"},
  "inferenceConfig": {"inferenceTemperature": 0.7},
  "useGuidedDecoding": true,
  "cacheResults": true
}

Field	Type	Required	Description
type	string	✓	Must be `simulated`
toolPersona	string	✓	How the model behaves when it simulates the tool’s output
modelIdentifier	object	✓	Hosted model that generates tool outputs
inferenceConfig	object	✓	Inference settings for that model; may be `{}`
useGuidedDecoding	boolean		Constrain output to the tool’s output schema while generating; defaults to `true`
cacheResults	boolean		Reuse the earlier result for a repeated call with identical arguments; defaults to `true`

MODELIDENTIFIER

Field	Type	Required	Description
modelType	string	✓	Hosted model provider
modelName	string	✓	Provider model name

modelType accepts ANTHROPIC_API, OPENAI_API, GEMINI_API, VERTEX_API, or OUMI_API. Only hosted models are accepted. Do not set apiKeys: Oumi resolves the provider key from the project’s API keys for each job.

INFERENCECONFIG

Field	Type	Description
inferenceTemperature	number	Sampling temperature
inferenceTopP	number	Nucleus sampling threshold, greater than `0` and at most `1`
inferenceMaxNewTokens	integer	Maximum number of generated tokens
inferenceSeed	integer	Seed for deterministic generation
requestsPerMinute	integer	Request rate limit
guidedDecoding	object	Not supported; use `useGuidedDecoding` instead

ENDPOINT CONFIG

{
  "type": "endpoint",
  "endpointUrl": "https://tools.example.com/orders/lookup",
  "protocol": {"type": "http", "method": "POST"},
  "auth": {"type": "bearer", "token": "YOUR_SERVICE_TOKEN", "scheme": "Bearer"},
  "timeoutSeconds": 30
}

Field	Type	Required	Description
type	string	✓	Must be `endpoint`
endpointUrl	string	✓	HTTPS URL that receives each tool call
protocol	object		How a call becomes a request; defaults to `{"type": "http", "method": "POST"}`
auth	object		Credential sent with each call; write-only
timeoutSeconds	integer		Seconds to wait for one call, from `1` to `120`; defaults to `30`

PROTOCOL

protocol.type selects one of two shapes.

Field	Type	Required	Description
type	string	✓	`http` sends one plain HTTP request per call
method	string		`GET`, `POST`, `PUT`, `PATCH`, or `DELETE`; defaults to `POST`

Field	Type	Required	Description
type	string	✓	`mcp` calls the endpoint as an MCP server over Streamable HTTP

With http, POST, PUT, and PATCH send the arguments as the JSON body. GET and DELETE send them as query parameters. Each request carries the X-Oumi-Call-Id and X-Oumi-Session-Id headers.

AUTH

auth.type selects one of two shapes.

Field	Type	Required	Description
type	string	✓	`bearer`
token	string	✓	Credential, up to 255 characters of letters, digits, `_`, `-`, `.`, or `=`
scheme	string		Scheme sent as `Authorization: <scheme> <token>`; defaults to `Bearer`

Field	Type	Required	Description
type	string	✓	`apiKey`
token	string	✓	Credential, sent on its own with no scheme
headerName	string	✓	Header that carries the token, such as `x-api-key`

scheme and headerName accept 1 to 64 letters, digits, or hyphens.

INTERACTIVE CONFIG

{"type": "interactive"}

Field	Type	Required	Description
type	string	✓	Must be `interactive`

The simulated user in the job answers each call. The served tool’s output schema, if it has one, must be an object with exactly one string property and must not require any other property.

IMPLEMENTATION RESPONSE

Create, get, and update requests return the implementation:

{
  "id": 412,
  "name": "projects/XFZ7K2/tools/87/implementations/412",
  "displayName": "Order Lookup",
  "implementationType": "lookup",
  "toolId": 87,
  "createdAt": "2026-10-01T17:04:12Z",
  "updatedAt": "2026-10-01T17:04:12Z"
}

Field	Type	Description
id	integer	Implementation ID
name	string	Resource name
displayName	string	Display name
implementationType	string	`lookup`, `simulated`, `endpoint`, or `interactive`
toolId	integer	ID of the tool this implementation serves
createdAt	string	Creation timestamp
updatedAt	string	Last update timestamp

The list route returns these objects in toolImplementations, with nextPageToken, previousPageToken, pageSize, and totalCount. It accepts the query parameters pagesize (1 to 100, default 50), pagetoken, sort_by (created_at or updated_at, default updated_at), and sort_direction (asc or desc, default desc).

CONFIG RESPONSE

GET .../config returns the stored configuration in the same shape as the create request, except for endpoint credentials. An endpoint’s auth omits token and returns stubbedToken instead:

{
  "type": "endpoint",
  "endpointUrl": "https://tools.example.com/orders/lookup",
  "protocol": {"type": "http", "method": "POST"},
  "auth": {"type": "bearer", "stubbedToken": "YOUR...OKEN", "scheme": "Bearer"}
}

stubbedToken shows the first and last four characters of a longer token and fully redacts a short one.

UPDATE REQUEST

PATCH accepts two fields. Omitted fields are left unchanged.

{
  "displayName": "Order Lookup v2",
  "auth": {"type": "apiKey", "headerName": "x-api-key", "token": "NEW_SERVICE_TOKEN"}
}

Field	Type	Required	Description
displayName	string		New display name
auth	object		Replacement credential for an endpoint implementation, in the AUTH shape; applies from the next job onward

EXECUTE REQUEST

POST .../implementations/{implementation_id}:execute runs one tool call the same way a job runs it.

{
  "arguments": {"orderId": "A-100"},
  "sessionId": "conversation-1"
}

Field	Type	Required	Description
arguments	object	✓	Tool arguments; must match the tool’s input schema and serialize to at most 64 KiB
sessionId	string		Groups calls into one conversation; an endpoint receives it with each call; generated when omitted

EXECUTE RESPONSE

{
  "output": {"status": "shipped"},
  "error": null,
  "callId": "6f1c2e0a9b7d4c3e8a5f2b1d0c9e8f7a",
  "sessionId": "conversation-1"
}

Field	Type	Description
output	any	The tool’s output; absent when the tool refused the call
error	string	Why the tool refused the call, in the tool’s own words
callId	string	Identifies this call; an endpoint receives it with the call
sessionId	string	The session the call ran in: the one you gave, or a generated one

A refusal returns status 200 with error set. Check error to tell a refusal from a null output.

Status	Meaning
`400`	The arguments do not match the tool’s input schema, exceed 64 KiB, or the endpoint’s answer does not match the tool’s output schema
`409`	The implementation is interactive, serves no tool, or has an unusable stored configuration
`502`	The endpoint did not answer usably
`504`	The endpoint did not answer within `timeoutSeconds`

VALIDATION RULES

config.type must be lookup, simulated, endpoint, or interactive.
Type and configuration cannot change after creation. PATCH changes only displayName and an endpoint’s auth.
auth in a PATCH is rejected for an implementation that is not an endpoint.
Lookup rows must have unique inputs, and the table must have at least one row.
A simulated modelIdentifier must be a hosted model and must not include apiKeys.
A simulated inferenceConfig must not include guidedDecoding.
endpointUrl must use HTTPS, and its host must resolve to a public address.
With GET or DELETE, every tool argument must be a scalar or an array of scalars, and no argument can share a name with a query parameter already in endpointUrl.
timeoutSeconds must be from 1 to 120.
An interactive implementation’s tool output schema must be an object with exactly one string property and no other required properties.
:execute requires editor access and a valid payment card on file for the organization. It is not available for interactive implementations.
Your organization’s plan limits the number of tool implementations.
In a job, attached implementations must serve tools with distinct names, every simulated implementation must use the same model, and any interactive implementation requires a user model.

Resources

Recipe configs

Agent schemas

Recipe examples

TOOL IMPLEMENTATION SCHEMA

OVERVIEW

CREATE REQUEST

LOOKUP CONFIG

SIMULATED CONFIG

MODELIDENTIFIER

INFERENCECONFIG

ENDPOINT CONFIG

PROTOCOL

AUTH

INTERACTIVE CONFIG

IMPLEMENTATION RESPONSE

CONFIG RESPONSE

UPDATE REQUEST

EXECUTE REQUEST

EXECUTE RESPONSE

VALIDATION RULES

​OVERVIEW

​CREATE REQUEST

​LOOKUP CONFIG

​SIMULATED CONFIG

​MODELIDENTIFIER

​INFERENCECONFIG

​ENDPOINT CONFIG

​PROTOCOL

​AUTH

​INTERACTIVE CONFIG

​IMPLEMENTATION RESPONSE

​CONFIG RESPONSE

​UPDATE REQUEST

​EXECUTE REQUEST

​EXECUTE RESPONSE

​VALIDATION RULES

OVERVIEW

CREATE REQUEST

LOOKUP CONFIG

SIMULATED CONFIG

MODELIDENTIFIER

INFERENCECONFIG

ENDPOINT CONFIG

PROTOCOL

AUTH

INTERACTIVE CONFIG

IMPLEMENTATION RESPONSE

CONFIG RESPONSE

UPDATE REQUEST

EXECUTE REQUEST

EXECUTE RESPONSE

VALIDATION RULES