Agents

Embed

<a href="https://referalli.com/docs/ref-agents"><img src="https://referalli.com/docs/_api/public/orgs/07f432f4-34b9-46a7-aaad-c0e395d2e4f9/spaces/2bf4f614-3630-4fbf-85f9-5ecafa6b7d97/pages/8b592eba-dca5-4900-bdf6-18c194e2a588/social-card.svg?v=3e7ae33eec8b" alt="Agents" width="600" height="315"></a>

POSThttps://referalli.com/v1/agents/register

Registers (or updates) an AI agent identity, proven by a wallet signature over a nonce from POST /v1/partner/auth/wallet/nonce. The nonce is single use and valid for 10 minutes. instantPayout pays the agent per outcome on the crypto rail. No API key: the signature is the credential.

Auth: none.

Request body application/json

walletAddressstringrequired

noncestringrequired

signaturestringrequired

namestring

modelstring

operatorstring

instantPayoutboolean

= false

{
  "walletAddress": "string",
  "nonce": "string",
  "signature": "string",
  "name": "string",
  "model": "string",
  "operator": "string",
  "instantPayout": false
}

Code samples

cURL

curl -X POST "https://referalli.com/v1/agents/register" \
  -H "Content-Type: application/json" \
  -d '{"walletAddress":"string","nonce":"string","signature":"string","name":"string","model":"string","operator":"string","instantPayout":false}'

TypeScript

const res = await fetch('https://referalli.com/v1/agents/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"walletAddress":"string","nonce":"string","signature":"string","name":"string","model":"string","operator":"string","instantPayout":false}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/agents/register",
    headers={
    "Content-Type": "application/json",
    },
    json={"walletAddress": "string", "nonce": "string", "signature": "string", "name": "string", "model": "string", "operator": "string", "instantPayout": False},
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/agents/register", strings.NewReader(`{"walletAddress":"string","nonce":"string","signature":"string","name":"string","model":"string","operator":"string","instantPayout":false}`))
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/agents/register');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"walletAddress":"string","nonce":"string","signature":"string","name":"string","model":"string","operator":"string","instantPayout":false}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/agents/register')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req.body = '{"walletAddress":"string","nonce":"string","signature":"string","name":"string","model":"string","operator":"string","instantPayout":false}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://referalli.com/v1/agents/register"))
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"walletAddress\":\"string\",\"nonce\":\"string\",\"signature\":\"string\",\"name\":\"string\",\"model\":\"string\",\"operator\":\"string\",\"instantPayout\":false}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "agentId": "string",
  "wallet": "string",
  "instantPayout": true
}

Schema

agentIdstringrequired

walletstringrequired

instantPayoutbooleanrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

401 Missing or invalid credentials. error.code is one of:

Example

{
  "error": {
    "code": "unauthorized",
    "message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
    "docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

404 No such resource. error.code is one of:

Example

{
  "error": {
    "code": "not_found",
    "message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
    "docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

429 Rate limited. error.code is one of:

Example

{
  "error": {
    "code": "rate_limited",
    "message": "an endpoint limit or the per-key quota was exceeded",
    "docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

500 Unexpected server error. error.code is one of:

Example

{
  "error": {
    "code": "internal_error",
    "message": "retry with backoff",
    "requestId": "req_8f2c1d4e5a6b7c8d",
    "docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

default Any other error, in the same envelope.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "requestId": "string",
    "docs_url": "string"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

POSThttps://referalli.com/t/{orgToken}/agent/attribute

Attribute a customer to an agent

An agent signs (programId, customerRef, nonce) to attribute a recommendation without a cookie or click. Enrolls the agent in the program, creates the referral unless the customer is already referred, and sets the agent's wallet as an instant crypto payout target. 401 for a bad signature, an expired nonce or an unregistered wallet.

Auth: none.

Parameters

orgTokenstringpathrequired

Request body application/json

walletAddressstringrequired

programIdstringrequired

customerRefstringrequired

noncestringrequired

signaturestringrequired

{
  "walletAddress": "string",
  "programId": "string",
  "customerRef": "string",
  "nonce": "string",
  "signature": "string"
}

Code samples

cURL

curl -X POST "https://referalli.com/t/{orgToken}/agent/attribute" \
  -H "Content-Type: application/json" \
  -d '{"walletAddress":"string","programId":"string","customerRef":"string","nonce":"string","signature":"string"}'

TypeScript

const res = await fetch('https://referalli.com/t/{orgToken}/agent/attribute', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"walletAddress":"string","programId":"string","customerRef":"string","nonce":"string","signature":"string"}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/t/{orgToken}/agent/attribute",
    headers={
    "Content-Type": "application/json",
    },
    json={"walletAddress": "string", "programId": "string", "customerRef": "string", "nonce": "string", "signature": "string"},
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/t/{orgToken}/agent/attribute", strings.NewReader(`{"walletAddress":"string","programId":"string","customerRef":"string","nonce":"string","signature":"string"}`))
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/t/{orgToken}/agent/attribute');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"walletAddress":"string","programId":"string","customerRef":"string","nonce":"string","signature":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/t/{orgToken}/agent/attribute')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req.body = '{"walletAddress":"string","programId":"string","customerRef":"string","nonce":"string","signature":"string"}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://referalli.com/t/{orgToken}/agent/attribute"))
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"walletAddress\":\"string\",\"programId\":\"string\",\"customerRef\":\"string\",\"nonce\":\"string\",\"signature\":\"string\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "attributed": true,
  "referralId": "string",
  "agentWallet": "string"
}

Schema

attributedbooleanrequired

referralIdstringrequired

agentWalletstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

401 Missing or invalid credentials. error.code is one of:

Example

{
  "error": {
    "code": "unauthorized",
    "message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
    "docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

404 No such resource. error.code is one of:

Example

{
  "error": {
    "code": "not_found",
    "message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
    "docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

429 Rate limited. error.code is one of:

Example

{
  "error": {
    "code": "rate_limited",
    "message": "an endpoint limit or the per-key quota was exceeded",
    "docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

500 Unexpected server error. error.code is one of:

Example

{
  "error": {
    "code": "internal_error",
    "message": "retry with backoff",
    "requestId": "req_8f2c1d4e5a6b7c8d",
    "docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

default Any other error, in the same envelope.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "requestId": "string",
    "docs_url": "string"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

POSThttps://referalli.com/t/{orgToken}/agent/negotiate

Negotiate a commission rate

An agent proposes a commission rate (proposedBps), signed with its wallet. The program's negotiation policy decides at once: accept enrolls the agent and publishes a new rule version with a partner override at the agreed rate; counter returns counterBps; reject explains why. 400 when the program isn't open to negotiation.

Auth: none.

Parameters

orgTokenstringpathrequired

Request body application/json

walletAddressstringrequired

programIdstringrequired

proposedBpsintegerrequired

noncestringrequired

signaturestringrequired

{
  "walletAddress": "string",
  "programId": "string",
  "proposedBps": 0,
  "nonce": "string",
  "signature": "string"
}

Code samples

cURL

curl -X POST "https://referalli.com/t/{orgToken}/agent/negotiate" \
  -H "Content-Type: application/json" \
  -d '{"walletAddress":"string","programId":"string","proposedBps":0,"nonce":"string","signature":"string"}'

TypeScript

const res = await fetch('https://referalli.com/t/{orgToken}/agent/negotiate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"walletAddress":"string","programId":"string","proposedBps":0,"nonce":"string","signature":"string"}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/t/{orgToken}/agent/negotiate",
    headers={
    "Content-Type": "application/json",
    },
    json={"walletAddress": "string", "programId": "string", "proposedBps": 0, "nonce": "string", "signature": "string"},
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/t/{orgToken}/agent/negotiate", strings.NewReader(`{"walletAddress":"string","programId":"string","proposedBps":0,"nonce":"string","signature":"string"}`))
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/t/{orgToken}/agent/negotiate');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"walletAddress":"string","programId":"string","proposedBps":0,"nonce":"string","signature":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/t/{orgToken}/agent/negotiate')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req.body = '{"walletAddress":"string","programId":"string","proposedBps":0,"nonce":"string","signature":"string"}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://referalli.com/t/{orgToken}/agent/negotiate"))
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"walletAddress\":\"string\",\"programId\":\"string\",\"proposedBps\":0,\"nonce\":\"string\",\"signature\":\"string\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "decision": "accept",
  "rateBps": 0,
  "counterBps": 0,
  "partnerId": "string",
  "reason": "string"
}

Schema

decisionstringrequired

accept | counter | reject

rateBpsinteger

counterBpsinteger

partnerIdstring

reasonstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

401 Missing or invalid credentials. error.code is one of:

Example

{
  "error": {
    "code": "unauthorized",
    "message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
    "docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

404 No such resource. error.code is one of:

Example

{
  "error": {
    "code": "not_found",
    "message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
    "docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

429 Rate limited. error.code is one of:

Example

{
  "error": {
    "code": "rate_limited",
    "message": "an endpoint limit or the per-key quota was exceeded",
    "docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

500 Unexpected server error. error.code is one of:

Example

{
  "error": {
    "code": "internal_error",
    "message": "retry with backoff",
    "requestId": "req_8f2c1d4e5a6b7c8d",
    "docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

default Any other error, in the same envelope.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "requestId": "string",
    "docs_url": "string"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

GEThttps://referalli.com/v1/programs/{id}/negotiation-policy

Get the agent negotiation policy

The program's negotiation policy, or null when it isn't open to negotiation.

Auth: an API key with programs:read (or full), or a session of any role.

Parameters

idstringpathrequired

x-org-idstringheader

With a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.

referalli-modestringheader

test runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.

live | test

Code samples

cURL

curl -X GET "https://referalli.com/v1/programs/{id}/negotiation-policy" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/programs/{id}/negotiation-policy', {
  method: 'GET',
  headers: {
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "GET",
    "https://referalli.com/v1/programs/{id}/negotiation-policy",
    headers={
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/v1/programs/{id}/negotiation-policy", nil)
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/programs/{id}/negotiation-policy');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/programs/{id}/negotiation-policy')
req = Net::HTTP::Get.new(uri)
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://referalli.com/v1/programs/{id}/negotiation-policy"))
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "negotiationPolicy": {}
}

Schema

negotiationPolicyGetOpenapiJsonResponserequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

401 Missing or invalid credentials. error.code is one of:

Example

{
  "error": {
    "code": "unauthorized",
    "message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
    "docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

403 Authenticated, but not allowed. error.code is one of:

Example

{
  "error": {
    "code": "forbidden",
    "message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
    "docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

404 No such resource. error.code is one of:

Example

{
  "error": {
    "code": "not_found",
    "message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
    "docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

429 Rate limited. error.code is one of:

Example

{
  "error": {
    "code": "rate_limited",
    "message": "an endpoint limit or the per-key quota was exceeded",
    "docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

500 Unexpected server error. error.code is one of:

Example

{
  "error": {
    "code": "internal_error",
    "message": "retry with backoff",
    "requestId": "req_8f2c1d4e5a6b7c8d",
    "docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

default Any other error, in the same envelope.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "requestId": "string",
    "docs_url": "string"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

PUThttps://referalli.com/v1/programs/{id}/negotiation-policy

Set the agent negotiation policy

What an agent may negotiate to in this program: rates between minBps and maxBps, accepted automatically up to autoAcceptMaxBps. Requires minBps <= autoAcceptMaxBps <= maxBps. enabled: false closes the program to negotiation.

Auth: an API key with programs:write (or full), or a session with role owner, admin.

Parameters

idstringpathrequired

Idempotency-Keystringheader

Any unique string up to 255 printable ASCII characters (a UUID). A retry with the same key within 24 hours gets the first response again (with idempotent-replayed: true) and nothing runs twice. The same key on a different request is 422 idempotency_key_reused; while the first is still running, 409 idempotency_in_progress.

x-org-idstringheader

With a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.

referalli-modestringheader

test runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.

live | test

Request body application/json

enabledboolean

= true

minBpsintegerrequired

maxBpsintegerrequired

autoAcceptMaxBpsintegerrequired

{
  "enabled": true,
  "minBps": 0,
  "maxBps": 0,
  "autoAcceptMaxBps": 0
}

Code samples

cURL

curl -X PUT "https://referalli.com/v1/programs/{id}/negotiation-policy" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"minBps":0,"maxBps":0,"autoAcceptMaxBps":0}'

TypeScript

const res = await fetch('https://referalli.com/v1/programs/{id}/negotiation-policy', {
  method: 'PUT',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"enabled":true,"minBps":0,"maxBps":0,"autoAcceptMaxBps":0}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "PUT",
    "https://referalli.com/v1/programs/{id}/negotiation-policy",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    "Content-Type": "application/json",
    },
    json={"enabled": True, "minBps": 0, "maxBps": 0, "autoAcceptMaxBps": 0},
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	req, _ := http.NewRequest("PUT", "https://referalli.com/v1/programs/{id}/negotiation-policy", strings.NewReader(`{"enabled":true,"minBps":0,"maxBps":0,"autoAcceptMaxBps":0}`))
	req.Header.Set("Idempotency-Key", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/programs/{id}/negotiation-policy');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'x-org-id: <value>', 'referalli-mode: <value>', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"enabled":true,"minBps":0,"maxBps":0,"autoAcceptMaxBps":0}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/programs/{id}/negotiation-policy')
req = Net::HTTP::Put.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"enabled":true,"minBps":0,"maxBps":0,"autoAcceptMaxBps":0}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://referalli.com/v1/programs/{id}/negotiation-policy"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .header("Content-Type", "application/json")
    .method("PUT", BodyPublishers.ofString("{\"enabled\":true,\"minBps\":0,\"maxBps\":0,\"autoAcceptMaxBps\":0}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "ok": true,
  "negotiationPolicy": {}
}

Schema

okbooleanrequired

negotiationPolicyGetOpenapiJsonResponserequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

401 Missing or invalid credentials. error.code is one of:

Example

{
  "error": {
    "code": "unauthorized",
    "message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
    "docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

403 Authenticated, but not allowed. error.code is one of:

Example

{
  "error": {
    "code": "forbidden",
    "message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
    "docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

404 No such resource. error.code is one of:

Example

{
  "error": {
    "code": "not_found",
    "message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
    "docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

409 The request conflicts with the current state. error.code is one of:

Example

{
  "error": {
    "code": "conflict",
    "message": "a unique value is taken, or the action would break a rule (the message says which)",
    "docs_url": "https://referalli.com/docs/errors-and-limits#conflict"
  }
}

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "a request with the same `idempotency-key` is still running",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_in_progress"
  }
}

{
  "error": {
    "code": "replay",
    "message": "a signed auth-connection call reused an id already received",
    "docs_url": "https://referalli.com/docs/errors-and-limits#replay"
  }
}

{
  "error": {
    "code": "live_mode_only",
    "message": "only changeable in live mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#live_mode_only"
  }
}

{
  "error": {
    "code": "test_mode_only",
    "message": "only exists in test mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#test_mode_only"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

422 The request cannot be processed as sent. error.code is one of:

Example

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "the `idempotency-key` was used for a different request",
    "docs_url": "https://referalli.com/docs/errors-and-limits#idempotency_key_reused"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "on the signed auth-connection endpoints",
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

429 Rate limited. error.code is one of:

Example

{
  "error": {
    "code": "rate_limited",
    "message": "an endpoint limit or the per-key quota was exceeded",
    "docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

500 Unexpected server error. error.code is one of:

Example

{
  "error": {
    "code": "internal_error",
    "message": "retry with backoff",
    "requestId": "req_8f2c1d4e5a6b7c8d",
    "docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

default Any other error, in the same envelope.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "requestId": "string",
    "docs_url": "string"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

GEThttps://referalli.com/v1/negotiations

List negotiation rounds

Agent negotiation rounds and their decisions, newest first, optionally for one program.

Auth: an API key with growth:read (or full), or a session of any role.

Parameters

programIdstringquery

limitintegerquery

Items per page, 1 to 100 (default 50). From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

= 50

starting_afterstringquery

A cursor: the id of an item (the previous page's next_cursor); returns the items after it. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

ending_beforestringquery

A cursor: returns the items before this item id (the previous page). Not with starting_after. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

created[gte]stringquery

Only items created at or after this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

created[lte]stringquery

Only items created at or before this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

referalli-versionstringheader

The API version to run the request under (2026-10-21, 2026-11-01). Default: the API key's pinned version, else 2026-10-21. The header name from before the rename is still accepted; this name wins when both are sent.

2026-10-21 | 2026-11-01

x-org-idstringheader

With a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.

referalli-modestringheader

test runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.

live | test

Code samples

cURL

curl -X GET "https://referalli.com/v1/negotiations?programId=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=" \
  -H "referalli-version: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/negotiations?programId=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=', {
  method: 'GET',
  headers: {
    'referalli-version': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "GET",
    "https://referalli.com/v1/negotiations?programId=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=",
    headers={
    "referalli-version": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/v1/negotiations?programId=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=", nil)
	req.Header.Set("referalli-version", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/negotiations?programId=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['referalli-version: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/negotiations?programId=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=')
req = Net::HTTP::Get.new(uri)
req['referalli-version'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://referalli.com/v1/negotiations?programId=&limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D="))
    .header("referalli-version", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 A page of the list. Under API version 2026-10-21 the body is the plain array instead.

Example

{
  "object": "string",
  "data": [
    {
      "id": "string",
      "programId": "string",
      "agentAccountId": "string",
      "proposedBps": 0,
      "decision": "string",
      "rateBps": 0,
      "round": 0,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}

Schema

objectstringrequired

dataobject[]required

Show child parameters

idstringrequired

programIdstringrequired

agentAccountIdstringrequired

proposedBpsintegerrequired

decisionstringrequired

rateBpsintegerrequired

roundintegerrequired

createdAtstringrequired

has_morebooleanrequired

Whether another page follows; pass next_cursor as starting_after to get it.

next_cursorstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

401 Missing or invalid credentials. error.code is one of:

Example

{
  "error": {
    "code": "unauthorized",
    "message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
    "docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

403 Authenticated, but not allowed. error.code is one of:

Example

{
  "error": {
    "code": "forbidden",
    "message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
    "docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

404 No such resource. error.code is one of:

Example

{
  "error": {
    "code": "not_found",
    "message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
    "docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

429 Rate limited. error.code is one of:

Example

{
  "error": {
    "code": "rate_limited",
    "message": "an endpoint limit or the per-key quota was exceeded",
    "docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

500 Unexpected server error. error.code is one of:

Example

{
  "error": {
    "code": "internal_error",
    "message": "retry with backoff",
    "requestId": "req_8f2c1d4e5a6b7c8d",
    "docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

default Any other error, in the same envelope.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "requestId": "string",
    "docs_url": "string"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

GEThttps://referalli.com/v1/agents

List partnered AI agents

The AI agents partnered with this org, with their wallet, metadata and how many recommendations each has attributed, most active first.

Auth: an API key with growth:read (or full), or a session with role owner, admin, analyst.

Parameters

limitintegerquery

Items per page, 1 to 100 (default 50). From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

= 50

starting_afterstringquery

A cursor: the id of an item (the previous page's next_cursor); returns the items after it. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

ending_beforestringquery

A cursor: returns the items before this item id (the previous page). Not with starting_after. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

created[gte]stringquery

Only items created at or after this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

created[lte]stringquery

Only items created at or before this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

referalli-versionstringheader

2026-10-21 | 2026-11-01

x-org-idstringheader

With a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.

referalli-modestringheader

test runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.

live | test

Code samples

cURL

curl -X GET "https://referalli.com/v1/agents?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=" \
  -H "referalli-version: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/agents?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=', {
  method: 'GET',
  headers: {
    'referalli-version': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "GET",
    "https://referalli.com/v1/agents?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=",
    headers={
    "referalli-version": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/v1/agents?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=", nil)
	req.Header.Set("referalli-version", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/agents?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['referalli-version: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/agents?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=')
req = Net::HTTP::Get.new(uri)
req['referalli-version'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://referalli.com/v1/agents?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D="))
    .header("referalli-version", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 A page of the list. Under API version 2026-10-21 the body is the plain array instead.

Example

{
  "object": "string",
  "data": [
    {
      "partnerId": "string",
      "accountId": "string",
      "name": "string",
      "wallet": "string",
      "metadata": {},
      "instantPayout": true,
      "status": "string",
      "recommendations": 0
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}

Schema

objectstringrequired

dataobject[]required

Show child parameters

partnerIdstringrequired

accountIdstringrequired

namestringrequired

walletstringrequired

metadataGetOpenapiJsonResponserequired

instantPayoutbooleanrequired

statusstringrequired

recommendationsintegerrequired

has_morebooleanrequired

Whether another page follows; pass next_cursor as starting_after to get it.

next_cursorstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

401 Missing or invalid credentials. error.code is one of:

Example

{
  "error": {
    "code": "unauthorized",
    "message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
    "docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

403 Authenticated, but not allowed. error.code is one of:

Example

{
  "error": {
    "code": "forbidden",
    "message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
    "docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

404 No such resource. error.code is one of:

Example

{
  "error": {
    "code": "not_found",
    "message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
    "docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

429 Rate limited. error.code is one of:

Example

{
  "error": {
    "code": "rate_limited",
    "message": "an endpoint limit or the per-key quota was exceeded",
    "docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

500 Unexpected server error. error.code is one of:

Example

{
  "error": {
    "code": "internal_error",
    "message": "retry with backoff",
    "requestId": "req_8f2c1d4e5a6b7c8d",
    "docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

default Any other error, in the same envelope.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "requestId": "string",
    "docs_url": "string"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

GEThttps://referalli.com/v1/agents/recommendations

List agent recommendations

Signed recommendations AI agents have attributed in this org, newest first.

Auth: an API key with growth:read (or full), or a session with role owner, admin, analyst.

Parameters

limitintegerquery

Items per page, 1 to 100 (default 50). From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

= 50

starting_afterstringquery

A cursor: the id of an item (the previous page's next_cursor); returns the items after it. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

ending_beforestringquery

A cursor: returns the items before this item id (the previous page). Not with starting_after. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

created[gte]stringquery

Only items created at or after this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

created[lte]stringquery

Only items created at or before this time (ISO 8601), on lists of timestamped records. From API version 2026-11-01; ignored under 2026-10-21, where lists are a capped plain array.

referalli-versionstringheader

2026-10-21 | 2026-11-01

x-org-idstringheader

With a session: the org to act in (the user must be a member). Not used with API keys, which belong to one org.

referalli-modestringheader

test runs a session request against the org's test data. With an API key it must match the key's mode (400 mode_mismatch otherwise). The header name from before the rename is still accepted.

live | test

Code samples

cURL

curl -X GET "https://referalli.com/v1/agents/recommendations?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=" \
  -H "referalli-version: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/agents/recommendations?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=', {
  method: 'GET',
  headers: {
    'referalli-version': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "GET",
    "https://referalli.com/v1/agents/recommendations?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=",
    headers={
    "referalli-version": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://referalli.com/v1/agents/recommendations?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=", nil)
	req.Header.Set("referalli-version", "<value>")
	req.Header.Set("x-org-id", "<value>")
	req.Header.Set("referalli-mode", "<value>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://referalli.com/v1/agents/recommendations?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['referalli-version: <value>', 'x-org-id: <value>', 'referalli-mode: <value>']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/agents/recommendations?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D=')
req = Net::HTTP::Get.new(uri)
req['referalli-version'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body

Java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://referalli.com/v1/agents/recommendations?limit=&starting_after=&ending_before=&created%5Bgte%5D=&created%5Blte%5D="))
    .header("referalli-version", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 A page of the list. Under API version 2026-10-21 the body is the plain array instead.

Example

{
  "object": "string",
  "data": [
    {
      "id": "string",
      "programId": "string",
      "customerRef": "string",
      "agent": "string",
      "wallet": "string",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}

Schema

objectstringrequired

dataobject[]required

Show child parameters

idstringrequired

programIdstringrequired

customerRefstringrequired

agentstringrequired

walletstringrequired

createdAtstringrequired

has_morebooleanrequired

Whether another page follows; pass next_cursor as starting_after to get it.

next_cursorstringrequired

400 The request is invalid. error.code is one of:

Example

{
  "error": {
    "code": "validation_error",
    "message": "the body or query failed validation, an unknown field was sent, the body is not valid json, or a session call has no `x-org-id`",
    "details": [
      {
        "code": "invalid_format",
        "path": [
          "destinationUrl"
        ],
        "message": "Invalid URL"
      }
    ],
    "docs_url": "https://referalli.com/docs/errors-and-limits#validation_error"
  }
}

{
  "error": {
    "code": "mode_mismatch",
    "message": "the `referalli-mode` header disagrees with the api key's mode",
    "docs_url": "https://referalli.com/docs/errors-and-limits#mode_mismatch"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "rejected by the http layer before the handler",
    "docs_url": "https://referalli.com/docs/errors-and-limits#bad_request"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

401 Missing or invalid credentials. error.code is one of:

Example

{
  "error": {
    "code": "unauthorized",
    "message": "no credentials, an unknown, revoked or expired api key or session, or a signature that did not verify",
    "docs_url": "https://referalli.com/docs/errors-and-limits#unauthorized"
  }
}

{
  "error": {
    "code": "step_up_required",
    "message": "a partner with two-factor on must send `x-totp-code`",
    "docs_url": "https://referalli.com/docs/errors-and-limits#step_up_required"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

403 Authenticated, but not allowed. error.code is one of:

Example

{
  "error": {
    "code": "forbidden",
    "message": "the wrong role, a key without the needed scope (the message names it), not a member, a suspended org, or a publishable key from an origin it does not allow",
    "docs_url": "https://referalli.com/docs/errors-and-limits#forbidden"
  }
}

{
  "error": {
    "code": "sso_required",
    "message": "this organization requires single sign-on",
    "docs_url": "https://referalli.com/docs/errors-and-limits#sso_required"
  }
}

{
  "error": {
    "code": "access_suspended",
    "message": "your identity provider suspended your access and you are the last owner",
    "docs_url": "https://referalli.com/docs/errors-and-limits#access_suspended"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

404 No such resource. error.code is one of:

Example

{
  "error": {
    "code": "not_found",
    "message": "the resource does not exist in this org (ids from other orgs look the same), a referenced id does not exist, a list cursor is not in the list, or the endpoint does not exist",
    "docs_url": "https://referalli.com/docs/errors-and-limits#not_found"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

429 Rate limited. error.code is one of:

Example

{
  "error": {
    "code": "rate_limited",
    "message": "an endpoint limit or the per-key quota was exceeded",
    "docs_url": "https://referalli.com/docs/errors-and-limits#rate_limited"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

500 Unexpected server error. error.code is one of:

Example

{
  "error": {
    "code": "internal_error",
    "message": "retry with backoff",
    "requestId": "req_8f2c1d4e5a6b7c8d",
    "docs_url": "https://referalli.com/docs/errors-and-limits#internal_error"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

default Any other error, in the same envelope.

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "requestId": "string",
    "docs_url": "string"
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

details

requestIdstring

docs_urlstringrequired

The docs entry for this error code: what it means and how to fix it.

Updated Oct 23, 2026

Was this page helpful?