v0.1.0

Oystara API Documentation

One API for partner platforms.

Quickstart

Create an API key, connect a provider, then read partners and conversions through one interface.

Get an API key

Sign in and generate an API key from the dashboard.

Open dashboard

Create a connection

Link a provider account. Rewardful uses api_secret; Tapfiliate/Tolt use api_key; FirstPromoter needs api_key + account_id.

curl -X POST "https://api.oystara.com/v1/connections" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "rewardful",
    "name": "Acme Rewardful",
    "credentials": { "api_secret": "…" }
  }'

List partners

Read normalized partners for that connection. Pass the connection id on every data request.

curl -X GET "https://api.oystara.com/v1/partners?limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Connection-Id: {connection_id}"

List conversions

Pull sales and referrals through the same schema.

curl -X GET "https://api.oystara.com/v1/conversions?limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Connection-Id: {connection_id}"

Subscribe to webhooks

Receive partner.created, conversion.created, commission.created, and commission.updated on your own URL.

curl -X POST "https://api.oystara.com/v1/webhook-endpoints" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/oystara"
  }'

Key concepts

One schema across every connector. Providers disagree on names — Oystara does not.

Partner

Affiliate, referrer, creator, ambassador, or reseller — normalized across providers.

Conversion

A sale or referral event.

Commission

A payout owed on a conversion.

Connection

A linked provider account. Credentials are never returned.

Webhook endpoint

An outbound URL that receives partner, conversion, and commission events.

Remote data

Set include_remote_data=true on list and get calls to attach the raw provider payload on each object. Omit it to keep responses normalized and small.

Authentication

Product routes take a bearer API key (oys_... ). Partners, conversions, and commissions also need X-Connection-Id.

Authorization: Bearer YOUR_API_KEY
X-Connection-Id: {connection_id}

Keep keys private. Never commit them or expose them in client-side code.

Pagination

List endpoints return a cursor envelope. Amounts are integer minor units plus an ISO currency.

  • limit — default 25, maximum 100
  • starting_after — last id from the previous page
  • created_after / created_before — ISO-8601 filters
  • partner_id, program_id, include_remote_data
{
  "data": [],
  "has_more": true,
  "next_cursor": "ptr_..."
}

Partners

get/v1/partners

List partners

Parameters

Header
X-Connection-Idstringrequired

Selects which provider connection to use

Format: uuid
Query
limitinteger
Format: int64Default: 25Min: 1Max: 100
starting_afterstring
partner_idstring
program_idstring
include_remote_databoolean
created_afterstring
Format: date-time
created_beforestring
Format: date-time

Example request

curl -X GET "https://api.oystara.com/v1/partners?limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Connection-Id: {connection_id}"
get/v1/partners/{id}

Get partner

Parameters

Header
X-Connection-Idstringrequired
Format: uuid
Path
idstringrequired

Example request

curl -X GET "https://api.oystara.com/v1/partners/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Connection-Id: {connection_id}"

Conversions

get/v1/conversions

List conversions

Parameters

Header
X-Connection-Idstringrequired

Selects which provider connection to use

Format: uuid
Query
limitinteger
Format: int64Default: 25Min: 1Max: 100
starting_afterstring
partner_idstring
program_idstring
include_remote_databoolean
created_afterstring
Format: date-time
created_beforestring
Format: date-time

Example request

curl -X GET "https://api.oystara.com/v1/conversions?limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Connection-Id: {connection_id}"
get/v1/conversions/{id}

Get conversion

Parameters

Header
X-Connection-Idstringrequired
Format: uuid
Path
idstringrequired

Example request

curl -X GET "https://api.oystara.com/v1/conversions/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Connection-Id: {connection_id}"

Commissions

get/v1/commissions

List commissions

Parameters

Header
X-Connection-Idstringrequired

Selects which provider connection to use

Format: uuid
Query
limitinteger
Format: int64Default: 25Min: 1Max: 100
starting_afterstring
partner_idstring
program_idstring
include_remote_databoolean
created_afterstring
Format: date-time
created_beforestring
Format: date-time

Example request

curl -X GET "https://api.oystara.com/v1/commissions?limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Connection-Id: {connection_id}"
get/v1/commissions/{id}

Get commission

Parameters

Header
X-Connection-Idstringrequired
Format: uuid
Path
idstringrequired

Example request

curl -X GET "https://api.oystara.com/v1/commissions/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Connection-Id: {connection_id}"

Connections

get/v1/connections

List connections

Example request

curl -X GET "https://api.oystara.com/v1/connections" \
  -H "Authorization: Bearer YOUR_API_KEY"
post/v1/connections

Create connection

Example request

curl -X POST "https://api.oystara.com/v1/connections" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": {
      "api_secret": "…"
    },
    "name": "Acme Partners",
    "program_id": "example_string",
    "provider": "rewardful"
  }'
delete/v1/connections/{id}

Soft-delete connection

Parameters

Path
idstringrequired

Example request

curl -X DELETE "https://api.oystara.com/v1/connections/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"
get/v1/connections/{id}

Get connection

Parameters

Path
idstringrequired

Example request

curl -X GET "https://api.oystara.com/v1/connections/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Webhook Endpoints

get/v1/webhook-endpoints

List outbound webhook endpoints

Example request

curl -X GET "https://api.oystara.com/v1/webhook-endpoints" \
  -H "Authorization: Bearer YOUR_API_KEY"
post/v1/webhook-endpoints

Create webhook endpoint

Example request

curl -X POST "https://api.oystara.com/v1/webhook-endpoints" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com"
  }'
delete/v1/webhook-endpoints/{id}

Soft-delete webhook endpoint

Parameters

Path
idstringrequired

Example request

curl -X DELETE "https://api.oystara.com/v1/webhook-endpoints/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Ingest

post/v1/ingest/{provider}/{connection_id}

Inbound provider webhook

Parameters

Path
providerstringrequired
connection_idstringrequired

Example request

curl -X POST "https://api.oystara.com/v1/ingest/rewardful/{connection_id}" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @payload.bin

© 2026 Oystara. All rights reserved.