APIs

Every published tool on Rival is callable over HTTP. Whether you’re integrating a tool into your application, calling it from a script, or wiring it into a pipeline, the API is the same.

Authentication

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

API keys are organization-wide. Any valid key belonging to your organization can call any tool the organization has access to. You don’t need a separate key per tool.

Pass the key in the Authorization header of every request. No Bearer prefix - just the key itself:

Authorization: your-api-key-here

Treat API keys like passwords. Don’t expose them in client-side code, public repositories, or anywhere they could be read by an unauthorized party. If a key is compromised, rotate it immediately.

The invocation endpoint

Tools are called with a POST request. The URL includes the tool ID and the version you want to call:

POST https://cortexconnect.rival.io/api/v1/functions/{function_id}/{version}/invoke

Where:

{function_id} is the Tool ID, shown on the tool’s detail page in the app and on its Marketplace listing.
{version} is a published version number (e.g. 1.0, 2.1). Omit the version to be routed to the latest published version.

Request format

The request body is a JSON object with a single key, event, containing the input payload your tool expects:

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

The shape of event is whatever the tool’s input schema defines - check the tool’s detail page for the documented inputs. See Events & Test Cases for the broader concept.

Response format

Responses are JSON objects with two fields:

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

statusCode is whatever your handler returned. 200 for success, 500 for an unhandled exception, or any code your handler explicitly returns.
body is a JSON string. 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://cortexconnect.rival.io/api/v1/functions/fn_abc123/1.0/invoke \
  -H "Authorization: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "event": {
      "name": "world"
    }
  }'

Error codes

Some errors are returned by the platform before your handler runs:

Code	Meaning	Charged?
`400`	Malformed request (invalid JSON, missing `event` field)	No
`401`	API key is missing or invalid	No
`402`	Insufficient run balance - top up in Settings - Billing	No
`404`	Tool ID or version does not exist	No
`408`	Handler exceeded the timeout limit	No
`500`	Unhandled exception thrown by your handler	Yes

A 402 or 408 means your code never ran or was terminated before completion - no charge applies. A 500 means your handler did run but threw, so the run is charged.

For runtime error shapes, MCP error codes, and more detail on each error, see the Error Reference.

Notes on API key scope

Because API keys are organization-wide:

Anyone with a key can call any tool the organization owns or has added.
Don’t ship keys in client-side code or commit them to version control.
Rotate keys before they expire to avoid interruptions.

Set a calendar reminder near the key’s expiry date - the app also surfaces a warning as the date approaches.