APIs

Every tool published on Rival is callable via HTTP. Whether you are integrating a tool into your application, testing from the command line, or building an automated pipeline, the API is how you interact with tools programmatically.

Authentication

API requests are authenticated with an API key. Keys are created in Workspace Settings → API in Dashboard. Each key has an expiry date - when a key expires, requests authenticated with it will be rejected.

API keys are organization-wide. Any valid key belonging to your organization can call any tool that the organization has access to. There is no need to create separate keys per tool.

Pass the key in the Authorization header of every request. Do not include a Bearer prefix - just the key itself:

Authorization: your-api-key-here

The invocation endpoint

Tools are invoked with a POST request. The endpoint includes the function ID and the version you want to call:

POST https://api.rival.io/v1/execute/{functionId}/{version}

If you omit the version, the request is routed to the latest published version of the tool. To pin to a specific version, include it explicitly (e.g., 1.0, 2.1).

The function ID and available versions are shown on the tool’s detail page in Dashboard and on the marketplace.

Request format

The request body is a JSON object with a single key, event, which contains the input payload for your tool:

{
  "event": {
    "param1": "value1",
    "param2": 42
  }
}

The shape of event depends on the tool’s input schema, which is documented on the tool’s detail page.

Response format

Responses are JSON objects with two fields:

{
  "statusCode": 200,
  "body": "..."
}

The statusCode reflects the outcome of your handler - 200 for success, 500 for an unhandled exception, or any other code your handler returns intentionally. The body field is always a JSON string, so parse it to read the actual content:

const response = await fetch(...);
const result = await response.json();
const body = JSON.parse(result.body);

Example: calling a tool with curl

curl -X POST https://api.rival.io/v1/execute/fn_abc123/1.0 \
  -H "Authorization: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "event": {
      "name": "world"
    }
  }'

Error codes

The platform returns these HTTP-level errors before your handler runs:

Code	Meaning
`401`	API key is missing or invalid
`402`	Insufficient credit balance - top up in Settings → Billing
`404`	Function ID or version does not exist
`408`	Handler exceeded the timeout limit
`500`	Unhandled exception thrown by your handler

A 402 means execution was blocked before your code ran - you are not charged. A 408 timeout is also not charged. A 500 is charged because your code did execute.

For the full error reference including runtime error shapes and MCP error codes, see Error Reference.

Notes on API key scope

Because API keys are organization-wide, treat them like passwords. Do not expose them in client-side code, public repositories, or anywhere they could be read by unauthorized parties. If a key is compromised, rotate it immediately from Workspace Settings → API.

Keys have expiry dates - set a reminder to rotate them before they expire to avoid service interruptions.