Developers

Embed

<a href="https://referalli.com/docs/ref-developers"><img src="https://referalli.com/docs/_api/public/orgs/07f432f4-34b9-46a7-aaad-c0e395d2e4f9/spaces/2bf4f614-3630-4fbf-85f9-5ecafa6b7d97/pages/a1cab484-b2c9-4ce1-8009-b5916b8084a3/social-card.svg?v=3e7ae33eec8b" alt="Developers" width="600" height="315"></a>

GEThttps://referalli.com/v1/api-keys

List API keys

Every key of the org, live and test (a test-mode caller sees test keys only), oldest first, with scopes, pinned version, owner, expiry and last use. Never returns the secret. Filter by mode or owner.

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

Parameters

modestringquery

Only live or only test keys; default both.

live | test

ownerstringquery

Only keys with this owner.

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/api-keys?mode=&owner=&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/api-keys?mode=&owner=&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/api-keys?mode=&owner=&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/api-keys?mode=&owner=&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/api-keys?mode=&owner=&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/api-keys?mode=&owner=&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/api-keys?mode=&owner=&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",
      "name": "string",
      "prefix": "string",
      "scopes": [
        "string"
      ],
      "apiVersion": "string",
      "publishable": true,
      "allowedOrigins": [
        "string"
      ],
      "livemode": true,
      "owner": "string",
      "pairId": "string",
      "createdBy": {
        "type": null,
        "id": null
      },
      "expiresAt": "2024-01-01T00:00:00Z",
      "expired": true,
      "lastUsedAt": "2024-01-01T00:00:00Z",
      "createdAt": "2024-01-01T00:00:00Z",
      "revokedAt": "2024-01-01T00:00:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}

Schema

objectstringrequired

dataApiKey[]required

Show child parameters

idstringrequired

namestringrequired

prefixstringrequired

scopesstring[]required

apiVersionstringrequired

The API version this key is pinned to (what it gets without a Referalli-Version header).

publishablebooleanrequired

allowedOriginsstring[]required

livemodebooleanrequired

ownerstringrequired

The developer or service the key belongs to.

pairIdstringrequired

Shared by a live/test pair minted together.

createdByobjectrequired

Show child parameters

typestringrequired

api_key | user

idstringrequired

expiresAtstringrequired

expiredbooleanrequired

lastUsedAtstringrequired

Updated at most once a minute.

createdAtstringrequired

revokedAtstringrequired

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.

POSThttps://referalli.com/v1/api-keys

Create an API key

Mints a secret key (rk_live_… / rk_test_…), shown only in this response. scopes defaults to full; a key can't grant scopes it doesn't hold. mode picks live, test or a matching pair of both (both returns { pairId, live, test }); a test-mode caller can mint test keys only. publishable: true mints a browser-safe rk_pub_ key limited to programs:read and events:write from allowedOrigins. apiVersion pins the key (default: latest). Needs an owner or admin session, or an API key with the admin scope. Audited.

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

Parameters

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

namestringrequired

scopesstring[]

publishableboolean

allowedOriginsstring[]

apiVersionstring

modestring

live | test | both

ownerstring

expiresInDaysinteger

{
  "name": "string",
  "scopes": [
    "admin"
  ],
  "publishable": true,
  "allowedOrigins": [
    "string"
  ],
  "apiVersion": "string",
  "mode": "live",
  "owner": "string",
  "expiresInDays": 0
}

Code samples

cURL

curl -X POST "https://referalli.com/v1/api-keys" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","scopes":["admin"],"publishable":true,"allowedOrigins":["string"],"apiVersion":"string","mode":"live","owner":"string","expiresInDays":0}'

TypeScript

const res = await fetch('https://referalli.com/v1/api-keys', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"name":"string","scopes":["admin"],"publishable":true,"allowedOrigins":["string"],"apiVersion":"string","mode":"live","owner":"string","expiresInDays":0}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/api-keys",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    "Content-Type": "application/json",
    },
    json={"name": "string", "scopes": ["admin"], "publishable": True, "allowedOrigins": ["string"], "apiVersion": "string", "mode": "live", "owner": "string", "expiresInDays": 0},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/api-keys", strings.NewReader(`{"name":"string","scopes":["admin"],"publishable":true,"allowedOrigins":["string"],"apiVersion":"string","mode":"live","owner":"string","expiresInDays":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/api-keys');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
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, '{"name":"string","scopes":["admin"],"publishable":true,"allowedOrigins":["string"],"apiVersion":"string","mode":"live","owner":"string","expiresInDays":0}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/api-keys')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"name":"string","scopes":["admin"],"publishable":true,"allowedOrigins":["string"],"apiVersion":"string","mode":"live","owner":"string","expiresInDays":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/api-keys"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"name\":\"string\",\"scopes\":[\"admin\"],\"publishable\":true,\"allowedOrigins\":[\"string\"],\"apiVersion\":\"string\",\"mode\":\"live\",\"owner\":\"string\",\"expiresInDays\":0}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "id": "string",
  "key": "string",
  "scopes": [
    "string"
  ],
  "publishable": true,
  "allowedOrigins": [
    "string"
  ],
  "apiVersion": "string",
  "livemode": true,
  "owner": "string",
  "expiresAt": "2024-01-01T00:00:00Z",
  "pairId": "string"
}

IssuedApiKey

idstringrequired

keystringrequired

The full key, shown once.

scopesstring[]required

publishablebooleanrequired

allowedOriginsstring[]required

apiVersionstringrequired

livemodebooleanrequired

False for a test-mode key (rk_test_…).

ownerstringrequired

expiresAtstringrequired

pairIdstringrequired

{
  "id": "string",
  "key": "string",
  "scopes": [
    "string"
  ],
  "publishable": true,
  "allowedOrigins": [
    "string"
  ],
  "apiVersion": "string",
  "livemode": true,
  "owner": "string",
  "expiresAt": "2024-01-01T00:00:00Z",
  "pairId": "string"
}

Option 2

pairIdstringrequired

liveobjectrequired

Show child parameters

idstringrequired

keystringrequired

The full key, shown once.

scopesstring[]required

publishablebooleanrequired

allowedOriginsstring[]required

apiVersionstringrequired

livemodebooleanrequired

False for a test-mode key (rk_test_…).

ownerstringrequired

expiresAtstringrequired

pairIdstringrequired

testobjectrequired

Show child parameters

idstringrequired

keystringrequired

The full key, shown once.

scopesstring[]required

publishablebooleanrequired

allowedOriginsstring[]required

apiVersionstringrequired

livemodebooleanrequired

False for a test-mode key (rk_test_…).

ownerstringrequired

expiresAtstringrequired

pairIdstringrequired

{
  "pairId": "string",
  "live": {
    "id": "string",
    "key": "string",
    "scopes": [
      "string"
    ],
    "publishable": true,
    "allowedOrigins": [
      "string"
    ],
    "apiVersion": "string",
    "livemode": true,
    "owner": "string",
    "expiresAt": "2024-01-01T00:00:00Z",
    "pairId": "string"
  },
  "test": {
    "id": "string",
    "key": "string",
    "scopes": [
      "string"
    ],
    "publishable": true,
    "allowedOrigins": [
      "string"
    ],
    "apiVersion": "string",
    "livemode": true,
    "owner": "string",
    "expiresAt": "2024-01-01T00:00:00Z",
    "pairId": "string"
  }
}

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/api-keys/{id}

Get an API key

One key of the org, without its secret.

Auth: an API key with team: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/api-keys/{id}" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/api-keys/{id}', {
  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/api-keys/{id}",
    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/api-keys/{id}", 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/api-keys/{id}');
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/api-keys/{id}')
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/api-keys/{id}"))
    .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

{
  "id": "string",
  "name": "string",
  "prefix": "string",
  "scopes": [
    "string"
  ],
  "apiVersion": "string",
  "publishable": true,
  "allowedOrigins": [
    "string"
  ],
  "livemode": true,
  "owner": "string",
  "pairId": "string",
  "createdBy": {
    "type": "api_key",
    "id": "string"
  },
  "expiresAt": "2024-01-01T00:00:00Z",
  "expired": true,
  "lastUsedAt": "2024-01-01T00:00:00Z",
  "createdAt": "2024-01-01T00:00:00Z",
  "revokedAt": "2024-01-01T00:00:00Z"
}

Schema

idstringrequired

namestringrequired

prefixstringrequired

scopesstring[]required

apiVersionstringrequired

The API version this key is pinned to (what it gets without a Referalli-Version header).

publishablebooleanrequired

allowedOriginsstring[]required

livemodebooleanrequired

ownerstringrequired

The developer or service the key belongs to.

pairIdstringrequired

Shared by a live/test pair minted together.

createdByobjectrequired

Show child parameters

typestringrequired

api_key | user

idstringrequired

expiresAtstringrequired

expiredbooleanrequired

lastUsedAtstringrequired

Updated at most once a minute.

createdAtstringrequired

revokedAtstringrequired

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.

DELETEhttps://referalli.com/v1/api-keys/{id}

Revoke an API key

Revokes a key at once. cascade=true also revokes every key it minted (and theirs); pair=true also revokes its live/test twin. Returns the revoked ids. Needs an owner or admin session, or an API key with the admin scope. Audited.

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

Parameters

idstringpathrequired

cascadestringquery

true: also revoke every key this key minted, and theirs.

true | false

pairstringquery

true: also revoke its live/test twin.

true | false

Idempotency-Keystringheader

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 DELETE "https://referalli.com/v1/api-keys/{id}?cascade=&pair=" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/api-keys/{id}?cascade=&pair=', {
  method: 'DELETE',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "DELETE",
    "https://referalli.com/v1/api-keys/{id}?cascade=&pair=",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://referalli.com/v1/api-keys/{id}?cascade=&pair=", nil)
	req.Header.Set("Idempotency-Key", "<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/api-keys/{id}?cascade=&pair=');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <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/api-keys/{id}?cascade=&pair=')
req = Net::HTTP::Delete.new(uri)
req['Idempotency-Key'] = '<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/api-keys/{id}?cascade=&pair="))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .method("DELETE", BodyPublishers.noBody())
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "ok": true,
  "revoked": [
    "string"
  ]
}

Schema

okbooleanrequired

revokedstring[]required

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.

PATCHhttps://referalli.com/v1/api-keys/{id}

Update an API key

Changes a key's pinned apiVersion, owner or expiry (expiresInDays from now; null removes it). Revoked keys are 404. Needs an owner or admin session, or an API key with the admin scope. Audited.

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

Parameters

idstringpathrequired

Idempotency-Keystringheader

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

apiVersionstring

ownerstring

expiresInDaysinteger

{
  "apiVersion": "string",
  "owner": "string",
  "expiresInDays": 0
}

Code samples

cURL

curl -X PATCH "https://referalli.com/v1/api-keys/{id}" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>" \
  -H "Content-Type: application/json" \
  -d '{"apiVersion":"string","owner":"string","expiresInDays":0}'

TypeScript

const res = await fetch('https://referalli.com/v1/api-keys/{id}', {
  method: 'PATCH',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"apiVersion":"string","owner":"string","expiresInDays":0}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "PATCH",
    "https://referalli.com/v1/api-keys/{id}",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    "Content-Type": "application/json",
    },
    json={"apiVersion": "string", "owner": "string", "expiresInDays": 0},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("PATCH", "https://referalli.com/v1/api-keys/{id}", strings.NewReader(`{"apiVersion":"string","owner":"string","expiresInDays":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/api-keys/{id}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
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, '{"apiVersion":"string","owner":"string","expiresInDays":0}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/api-keys/{id}')
req = Net::HTTP::Patch.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"apiVersion":"string","owner":"string","expiresInDays":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/api-keys/{id}"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .header("Content-Type", "application/json")
    .method("PATCH", BodyPublishers.ofString("{\"apiVersion\":\"string\",\"owner\":\"string\",\"expiresInDays\":0}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "id": "string",
  "apiVersion": "string",
  "owner": "string",
  "expiresAt": "2024-01-01T00:00:00Z"
}

Schema

idstringrequired

apiVersionstringrequired

ownerstringrequired

expiresAtstringrequired

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/audit-logs

List audit log entries

Every change recorded in the org, newest first: who did it (actor, actorType), what (action; a trailing * matches a prefix such as payout.*) and to what (subjectType, subjectId). Filter by any of those and by created[gte]/created[lte].

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

Parameters

actorstringquery

Actor id: a user, API key or connection id.

actorTypestringquery

actionstringquery

Exact action, or a prefix ending in * (e.g. payout.*).

subjectTypestringquery

subjectIdstringquery

created[gte]stringquery

created[lte]stringquery

limitintegerquery

= 50

starting_afterstringquery

An entry id: return the entries after it.

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.

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/audit-logs?actor=&actorType=&action=&subjectType=&subjectId=&created%5Bgte%5D=&created%5Blte%5D=&limit=&starting_after=&ending_before=" \
  -H "referalli-version: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/audit-logs?actor=&actorType=&action=&subjectType=&subjectId=&created%5Bgte%5D=&created%5Blte%5D=&limit=&starting_after=&ending_before=', {
  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/audit-logs?actor=&actorType=&action=&subjectType=&subjectId=&created%5Bgte%5D=&created%5Blte%5D=&limit=&starting_after=&ending_before=",
    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/audit-logs?actor=&actorType=&action=&subjectType=&subjectId=&created%5Bgte%5D=&created%5Blte%5D=&limit=&starting_after=&ending_before=", 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/audit-logs?actor=&actorType=&action=&subjectType=&subjectId=&created%5Bgte%5D=&created%5Blte%5D=&limit=&starting_after=&ending_before=');
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/audit-logs?actor=&actorType=&action=&subjectType=&subjectId=&created%5Bgte%5D=&created%5Blte%5D=&limit=&starting_after=&ending_before=')
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/audit-logs?actor=&actorType=&action=&subjectType=&subjectId=&created%5Bgte%5D=&created%5Blte%5D=&limit=&starting_after=&ending_before="))
    .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",
      "actorType": "string",
      "actorId": "string",
      "action": "string",
      "subjectType": "string",
      "subjectId": "string",
      "data": {},
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}

Schema

objectstringrequired

dataAuditLogEntry[]required

Show child parameters

idstringrequired

actorTypestringrequired

actorIdstringrequired

actionstringrequired

subjectTypestringrequired

subjectIdstringrequired

dataobjectrequired

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/test_clock

Get the test clock

Test mode only (409 test_mode_only otherwise). The test org's current time and how far it has been advanced.

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

Parameters

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/test_clock" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/test_clock', {
  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/test_clock",
    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/test_clock", 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/test_clock');
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/test_clock')
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/test_clock"))
    .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

{
  "now": "2024-01-01T00:00:00Z",
  "offsetSeconds": 0
}

Schema

nowstringrequired

offsetSecondsintegerrequired

How far the test clock is ahead of real time.

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.

POSThttps://referalli.com/v1/test_clock/advance

Advance the test clock

Test mode only. Moves the test org's clock forward by seconds (never back), then runs what came due: held commissions are approved, payout schedules fire and retention purges run. Returns the new time and what ran. Audited.

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

Parameters

Idempotency-Keystringheader

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

secondsintegerrequired

{
  "seconds": 0
}

Code samples

cURL

curl -X POST "https://referalli.com/v1/test_clock/advance" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>" \
  -H "Content-Type: application/json" \
  -d '{"seconds":0}'

TypeScript

const res = await fetch('https://referalli.com/v1/test_clock/advance', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"seconds":0}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/test_clock/advance",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    "Content-Type": "application/json",
    },
    json={"seconds": 0},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/test_clock/advance", strings.NewReader(`{"seconds":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/test_clock/advance');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
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, '{"seconds":0}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/test_clock/advance')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"seconds":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/test_clock/advance"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"seconds\":0}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "now": "2024-01-01T00:00:00Z",
  "offsetSeconds": 0,
  "approved": 0,
  "payoutRuns": 0
}

Schema

nowstringrequired

offsetSecondsintegerrequired

approvedintegerrequired

Held commission lines approved because their hold ended.

payoutRunsintegerrequired

Scheduled payout runs that fell due and ran.

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/test/emails

List captured test emails

Test mode only. Emails the test org would have sent, captured instead of delivered, newest first.

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

Parameters

limitintegerquery

= 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/test/emails?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/test/emails?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/test/emails?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/test/emails?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/test/emails?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/test/emails?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/test/emails?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",
      "event": "string",
      "to": "string",
      "subject": "string",
      "text": "string",
      "html": "string",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}

Schema

objectstringrequired

dataobject[]required

Show child parameters

idstringrequired

eventstringrequired

tostringrequired

subjectstringrequired

textstringrequired

htmlstringrequired

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.

POSThttps://referalli.com/v1/cli/device-codes

Start a CLI sign-in

The CLI login command calls this to start a device sign-in: returns a deviceCode for polling and a userCode for the person to approve at verificationUri. Codes expire after 10 minutes. No authentication; limited per IP.

Auth: none.

Request body application/json

clientNamestring

{
  "clientName": "string"
}

Code samples

cURL

curl -X POST "https://referalli.com/v1/cli/device-codes" \
  -H "Content-Type: application/json" \
  -d '{"clientName":"string"}'

TypeScript

const res = await fetch('https://referalli.com/v1/cli/device-codes', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"clientName":"string"}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/cli/device-codes",
    headers={
    "Content-Type": "application/json",
    },
    json={"clientName": "string"},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/cli/device-codes", strings.NewReader(`{"clientName":"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/v1/cli/device-codes');
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, '{"clientName":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/cli/device-codes')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req.body = '{"clientName":"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/v1/cli/device-codes"))
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"clientName\":\"string\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "deviceCode": "string",
  "userCode": "string",
  "verificationUri": "string",
  "verificationUriComplete": "string",
  "expiresIn": 0,
  "interval": 0
}

Schema

deviceCodestringrequired

Secret: the CLI polls with it.

userCodestringrequired

verificationUristringrequired

verificationUriCompletestringrequired

expiresInintegerrequired

intervalintegerrequired

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.

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/v1/cli/device-codes/token

Poll a CLI sign-in

Polled by the CLI every interval seconds with its deviceCode. Answers pending, expired, denied or consumed, or once approved, approved with the new API key (returned once). Polling faster than allowed is 429.

Auth: none.

Request body application/json

deviceCodestringrequired

{
  "deviceCode": "string"
}

Code samples

cURL

curl -X POST "https://referalli.com/v1/cli/device-codes/token" \
  -H "Content-Type: application/json" \
  -d '{"deviceCode":"string"}'

TypeScript

const res = await fetch('https://referalli.com/v1/cli/device-codes/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"deviceCode":"string"}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/cli/device-codes/token",
    headers={
    "Content-Type": "application/json",
    },
    json={"deviceCode": "string"},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/cli/device-codes/token", strings.NewReader(`{"deviceCode":"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/v1/cli/device-codes/token');
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, '{"deviceCode":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/cli/device-codes/token')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req.body = '{"deviceCode":"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/v1/cli/device-codes/token"))
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"deviceCode\":\"string\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "status": "pending",
  "key": "string",
  "orgId": "string",
  "orgName": "string",
  "scopes": [
    "string"
  ]
}

Schema

statusstringrequired

pending | approved | denied | expired | consumed

keystring

The issued API key, returned once when approved.

orgIdstring

orgNamestring

scopesstring[]

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.

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/cli/device-codes/{userCode}

Get a pending CLI sign-in

For the approval page: the pending code, which CLI asked and when it expires. Needs a signed-in person (owner or admin). 404 when expired or used.

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

Parameters

userCodestringpathrequired

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/cli/device-codes/{userCode}" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/cli/device-codes/{userCode}', {
  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/cli/device-codes/{userCode}",
    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/cli/device-codes/{userCode}", 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/cli/device-codes/{userCode}');
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/cli/device-codes/{userCode}')
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/cli/device-codes/{userCode}"))
    .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

{
  "userCode": "string",
  "clientName": "string",
  "createdAt": "2024-01-01T00:00:00Z",
  "expiresAt": "2024-01-01T00:00:00Z"
}

Schema

userCodestringrequired

clientNamestringrequired

createdAtstringrequired

expiresAtstringrequired

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.

POSThttps://referalli.com/v1/cli/device-codes/{userCode}/approve

Approve a CLI sign-in

Approves the sign-in and mints its API key in this org. access picks the scopes: cli (webhooks write and read access to the rest, the default), read or full. Needs a signed-in owner or admin. Audited.

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

Parameters

userCodestringpathrequired

Idempotency-Keystringheader

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

accessstring

full | read | cli = cli

namestring

{
  "access": "cli",
  "name": "string"
}

Code samples

cURL

curl -X POST "https://referalli.com/v1/cli/device-codes/{userCode}/approve" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>" \
  -H "Content-Type: application/json" \
  -d '{"access":"cli","name":"string"}'

TypeScript

const res = await fetch('https://referalli.com/v1/cli/device-codes/{userCode}/approve', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"access":"cli","name":"string"}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/cli/device-codes/{userCode}/approve",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    "Content-Type": "application/json",
    },
    json={"access": "cli", "name": "string"},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/cli/device-codes/{userCode}/approve", strings.NewReader(`{"access":"cli","name":"string"}`))
	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/cli/device-codes/{userCode}/approve');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
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, '{"access":"cli","name":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/cli/device-codes/{userCode}/approve')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"access":"cli","name":"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/v1/cli/device-codes/{userCode}/approve"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"access\":\"cli\",\"name\":\"string\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "ok": true,
  "keyId": "string",
  "scopes": [
    "string"
  ]
}

Schema

okbooleanrequired

keyIdstringrequired

scopesstring[]required

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.

POSThttps://referalli.com/v1/cli/device-codes/{userCode}/deny

Deny a CLI sign-in

Refuses a pending sign-in; the CLI then sees denied.

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

Parameters

userCodestringpathrequired

Idempotency-Keystringheader

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 POST "https://referalli.com/v1/cli/device-codes/{userCode}/deny" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/cli/device-codes/{userCode}/deny', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/cli/device-codes/{userCode}/deny",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/cli/device-codes/{userCode}/deny", nil)
	req.Header.Set("Idempotency-Key", "<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/cli/device-codes/{userCode}/deny');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <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/cli/device-codes/{userCode}/deny')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<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/cli/device-codes/{userCode}/deny"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .method("POST", BodyPublishers.noBody())
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "ok": true
}

Schema

okbooleanrequired

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.

POSThttps://referalli.com/v1/cli/listeners

Open a CLI event listener

The CLI listen command opens a listener for some topics (default every topic). Events are queued for it while it polls at least every 2 minutes, and each comes with Standard Webhooks headers signed with the returned secret, so the CLI can forward them to a local server.

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

Parameters

Idempotency-Keystringheader

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

topicsstring[]

forwardTostring

{
  "topics": [
    "string"
  ],
  "forwardTo": "string"
}

Code samples

cURL

curl -X POST "https://referalli.com/v1/cli/listeners" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>" \
  -H "Content-Type: application/json" \
  -d '{"topics":["string"],"forwardTo":"string"}'

TypeScript

const res = await fetch('https://referalli.com/v1/cli/listeners', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"topics":["string"],"forwardTo":"string"}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/cli/listeners",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    "Content-Type": "application/json",
    },
    json={"topics": ["string"], "forwardTo": "string"},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/cli/listeners", strings.NewReader(`{"topics":["string"],"forwardTo":"string"}`))
	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/cli/listeners');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
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, '{"topics":["string"],"forwardTo":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/cli/listeners')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"topics":["string"],"forwardTo":"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/v1/cli/listeners"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"topics\":[\"string\"],\"forwardTo\":\"string\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "id": "string",
  "secret": "string",
  "topics": [
    "string"
  ],
  "idleTimeoutSec": 0
}

Schema

idstringrequired

secretstringrequired

Signs forwarded events (Standard Webhooks); shown once.

topicsstring[]required

idleTimeoutSecintegerrequired

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/cli/listeners/{id}/events

Receive listener events

Up to 50 queued events for the listener, oldest first, each with its body and signed headers. wait long-polls up to 25 seconds for the first event. Polling keeps the listener alive.

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

Parameters

idstringpathrequired

waitintegerquery

= 0

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/cli/listeners/{id}/events?wait=" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/cli/listeners/{id}/events?wait=', {
  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/cli/listeners/{id}/events?wait=",
    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/cli/listeners/{id}/events?wait=", 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/cli/listeners/{id}/events?wait=');
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/cli/listeners/{id}/events?wait=')
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/cli/listeners/{id}/events?wait="))
    .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

{
  "events": [
    {
      "id": "string",
      "eventId": "string",
      "topic": "string",
      "body": "string",
      "headers": {}
    }
  ]
}

Schema

eventsobject[]required

Show child parameters

idstringrequired

eventIdstringrequired

topicstringrequired

bodystringrequired

The exact bytes to forward.

headersobjectrequired

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.

DELETEhttps://referalli.com/v1/cli/listeners/{id}

Close a CLI listener

Closes the listener; queued events are dropped.

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

Parameters

idstringpathrequired

Idempotency-Keystringheader

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 DELETE "https://referalli.com/v1/cli/listeners/{id}" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/cli/listeners/{id}', {
  method: 'DELETE',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
  },
});
const data = await res.json();

Python

import requests

res = requests.request(
    "DELETE",
    "https://referalli.com/v1/cli/listeners/{id}",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    },
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://referalli.com/v1/cli/listeners/{id}", nil)
	req.Header.Set("Idempotency-Key", "<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/cli/listeners/{id}');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <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/cli/listeners/{id}')
req = Net::HTTP::Delete.new(uri)
req['Idempotency-Key'] = '<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/cli/listeners/{id}"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .method("DELETE", BodyPublishers.noBody())
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "ok": true
}

Schema

okbooleanrequired

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.

POSThttps://referalli.com/v1/cli/trigger

Send a test event

The CLI trigger command sends a realistic sample event (ids *_test_…, test: true) to the org's listeners and webhook endpoints. data overrides fields of the sample. 400 for a topic with no sample; GET /v1/cli/topics lists them.

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

Parameters

Idempotency-Keystringheader

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

topicstringrequired

dataobject

{
  "topic": "string",
  "data": {}
}

Code samples

cURL

curl -X POST "https://referalli.com/v1/cli/trigger" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>" \
  -H "Content-Type: application/json" \
  -d '{"topic":"string","data":{}}'

TypeScript

const res = await fetch('https://referalli.com/v1/cli/trigger', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"topic":"string","data":{}}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/cli/trigger",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    "Content-Type": "application/json",
    },
    json={"topic": "string", "data": {}},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/cli/trigger", strings.NewReader(`{"topic":"string","data":{}}`))
	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/cli/trigger');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
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, '{"topic":"string","data":{}}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/cli/trigger')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"topic":"string","data":{}}'
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/cli/trigger"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"topic\":\"string\",\"data\":{}}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "eventId": "string",
  "topic": "string",
  "payload": {},
  "deliveredTo": {
    "listeners": 0,
    "endpoints": 0
  }
}

Schema

eventIdstringrequired

topicstringrequired

payloadobjectrequired

deliveredToobjectrequired

Show child parameters

listenersintegerrequired

endpointsintegerrequired

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/cli/topics

List triggerable topics

The event topics POST /v1/cli/trigger can send.

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

Parameters

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/cli/topics" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/cli/topics', {
  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/cli/topics",
    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/cli/topics", 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/cli/topics');
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/cli/topics')
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/cli/topics"))
    .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

{
  "topics": [
    "string"
  ]
}

Schema

topicsstring[]required

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/cli/logs

Tail the request log

The CLI's logs tail command: the org's recent API requests (method, path without query string, status, latency, actor). The first call returns the latest 20 and a cursor; pass it as after (with wait to long-poll up to 25 seconds) for newer entries. Kept for a day.

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

Parameters

afterintegerquery

Return entries after this cursor.

waitintegerquery

= 0

limitintegerquery

= 50

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/cli/logs?after=&wait=&limit=" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/cli/logs?after=&wait=&limit=', {
  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/cli/logs?after=&wait=&limit=",
    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/cli/logs?after=&wait=&limit=", 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/cli/logs?after=&wait=&limit=');
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/cli/logs?after=&wait=&limit=')
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/cli/logs?after=&wait=&limit="))
    .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

{
  "entries": [
    {
      "seq": 0,
      "requestId": "string",
      "method": "string",
      "path": "string",
      "status": 0,
      "latencyMs": 0,
      "actorType": "string",
      "actorId": "string",
      "ts": "2024-01-01T00:00:00Z"
    }
  ],
  "cursor": 0
}

Schema

entriesobject[]required

Show child parameters

seqintegerrequired

requestIdstringrequired

methodstringrequired

pathstringrequired

statusintegerrequired

latencyMsintegerrequired

actorTypestringrequired

actorIdstringrequired

tsstringrequired

cursorintegerrequired

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.

POSThttps://referalli.com/v1/sandbox/simulate

Simulate billing history

Generates deterministic billing history through the real commission pipeline, so you can see commissions flow without a provider: a new sandbox customer referred to the partner, months (default 3) of subscription payments at priceMinor, then for scenario: "refund" a half refund of the first invoice or for churn a cancellation. Returns the customer and what was created. Audited.

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

Parameters

Idempotency-Keystringheader

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

programIdstringrequired

partnerIdstringrequired

scenariostring

subscription | refund | churn = subscription

priceMinorinteger

= 9900

monthsinteger

= 3

{
  "programId": "string",
  "partnerId": "string",
  "scenario": "subscription",
  "priceMinor": 9900,
  "months": 3
}

Code samples

cURL

curl -X POST "https://referalli.com/v1/sandbox/simulate" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>" \
  -H "Content-Type: application/json" \
  -d '{"programId":"string","partnerId":"string","scenario":"subscription","priceMinor":9900,"months":3}'

TypeScript

const res = await fetch('https://referalli.com/v1/sandbox/simulate', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"programId":"string","partnerId":"string","scenario":"subscription","priceMinor":9900,"months":3}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/sandbox/simulate",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    "Content-Type": "application/json",
    },
    json={"programId": "string", "partnerId": "string", "scenario": "subscription", "priceMinor": 9900, "months": 3},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/sandbox/simulate", strings.NewReader(`{"programId":"string","partnerId":"string","scenario":"subscription","priceMinor":9900,"months":3}`))
	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/sandbox/simulate');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
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, '{"programId":"string","partnerId":"string","scenario":"subscription","priceMinor":9900,"months":3}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/sandbox/simulate')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"programId":"string","partnerId":"string","scenario":"subscription","priceMinor":9900,"months":3}'
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/sandbox/simulate"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"programId\":\"string\",\"partnerId\":\"string\",\"scenario\":\"subscription\",\"priceMinor\":9900,\"months\":3}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "customerRef": "string",
  "events": 0,
  "conversions": 0,
  "linesCreated": 0,
  "reversals": 0
}

Schema

customerRefstringrequired

eventsintegerrequired

conversionsintegerrequired

linesCreatedintegerrequired

reversalsintegerrequired

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/graphql

Query the GraphQL read layer

A read-only GraphQL endpoint over the same org-scoped data as REST (programs, partners, referrals, analytics), with the same authentication. Mutations stay in REST.

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

Parameters

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/graphql" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>"

TypeScript

const res = await fetch('https://referalli.com/v1/graphql', {
  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/graphql",
    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/graphql", 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/graphql');
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/graphql')
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/graphql"))
    .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

{
  "data": {},
  "errors": [
    {}
  ]
}

Schema

dataGetOpenapiJsonResponse

errorsGetOpenapiJsonResponse[]

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.

POSThttps://referalli.com/v1/graphql

Query the GraphQL read layer (POST)

The GraphQL endpoint with the query in a JSON body. Read-only, so a read-scoped API key may call it.

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

Parameters

Idempotency-Keystringheader

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

querystringrequired

variablesobject

operationNamestring

{
  "query": "string",
  "variables": {},
  "operationName": "string"
}

Code samples

cURL

curl -X POST "https://referalli.com/v1/graphql" \
  -H "Idempotency-Key: <value>" \
  -H "x-org-id: <value>" \
  -H "referalli-mode: <value>" \
  -H "Content-Type: application/json" \
  -d '{"query":"string","variables":{},"operationName":"string"}'

TypeScript

const res = await fetch('https://referalli.com/v1/graphql', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'x-org-id': '<value>',
    'referalli-mode': '<value>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"query":"string","variables":{},"operationName":"string"}),
});
const data = await res.json();

Python

import requests

res = requests.request(
    "POST",
    "https://referalli.com/v1/graphql",
    headers={
    "Idempotency-Key": "<value>",
    "x-org-id": "<value>",
    "referalli-mode": "<value>",
    "Content-Type": "application/json",
    },
    json={"query": "string", "variables": {}, "operationName": "string"},
)
data = res.json()

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://referalli.com/v1/graphql", strings.NewReader(`{"query":"string","variables":{},"operationName":"string"}`))
	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/graphql');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
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, '{"query":"string","variables":{},"operationName":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Ruby

require 'net/http'
require 'uri'

uri = URI('https://referalli.com/v1/graphql')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['x-org-id'] = '<value>'
req['referalli-mode'] = '<value>'
req['Content-Type'] = 'application/json'
req.body = '{"query":"string","variables":{},"operationName":"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/v1/graphql"))
    .header("Idempotency-Key", "<value>")
    .header("x-org-id", "<value>")
    .header("referalli-mode", "<value>")
    .header("Content-Type", "application/json")
    .method("POST", BodyPublishers.ofString("{\"query\":\"string\",\"variables\":{},\"operationName\":\"string\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

Example

{
  "data": {},
  "errors": [
    {}
  ]
}

Schema

dataGetOpenapiJsonResponse

errorsGetOpenapiJsonResponse[]

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.

Updated Oct 23, 2026

Was this page helpful?