# Oystara API Documentation One API for partner platforms. Version `0.1.0`. ## Authentication oys_… API key. Send it as a bearer token. Data routes also require `X-Connection-Id`. ``` Authorization: Bearer YOUR_API_KEY X-Connection-Id: {connection_id} ``` ## Objects ### Partner Affiliate, referrer, creator, ambassador, or reseller — normalized across providers. - `created_at` (`string` required) - `email` (`string`) - `id` (`string` required) - `name` (`string`) - `program_id` (`string`) - `provider` (`string` required) - `remote_data` (`any`) - `remote_id` (`string` required) - `status` (`string` required) ### Conversion A sale or referral event. - `amount` (`integer` required) - `currency` (`string` required) - `customer_email` (`string`) - `id` (`string` required) - `occurred_at` (`string` required) - `partner_id` (`string`) - `provider` (`string` required) - `remote_data` (`any`) - `remote_id` (`string` required) - `status` (`string` required) ### Commission A payout owed on a conversion. - `amount` (`integer` required) - `conversion_id` (`string`) - `created_at` (`string` required) - `currency` (`string` required) - `id` (`string` required) - `partner_id` (`string`) - `provider` (`string` required) - `remote_data` (`any`) - `remote_id` (`string` required) - `status` (`string` required) ### PublicConnection A linked provider account. Credentials are never returned. - `created_at` (`string` required) - `id` (`string` required) - `name` (`string` required) - `program_id` (`string`) - `provider` (`string` required) - `status` (`string` required) ### WebhookEndpoint An outbound URL that receives partner, conversion, and commission events. - `created_at` (`string` required) - `id` (`string` required) - `url` (`string` required) ## Pagination List endpoints return `{ "data": [], "has_more": true, "next_cursor": "..." }`. Pass `starting_after` with the last id to fetch the next page. `limit` defaults to 25 (max 100). Optional filters: `partner_id`, `program_id`, `created_after`, `created_before`, `include_remote_data`. ## Partners ### List partners `GET /v1/partners` **Parameters** - `limit` (query, `integer`) - `starting_after` (query, `string`) - `partner_id` (query, `string`) - `program_id` (query, `string`) - `include_remote_data` (query, `boolean`) - `created_after` (query, `string`) - `created_before` (query, `string`) - `X-Connection-Id` (header, `string` required) — Selects which provider connection to use ```bash curl -X GET "https://api.oystara.com/v1/partners?limit=25" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "X-Connection-Id: {connection_id}" ``` ### Get partner `GET /v1/partners/{id}` **Parameters** - `id` (path, `string` required) - `X-Connection-Id` (header, `string` required) ```bash curl -X GET "https://api.oystara.com/v1/partners/{id}" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "X-Connection-Id: {connection_id}" ``` ## Conversions ### List conversions `GET /v1/conversions` **Parameters** - `limit` (query, `integer`) - `starting_after` (query, `string`) - `partner_id` (query, `string`) - `program_id` (query, `string`) - `include_remote_data` (query, `boolean`) - `created_after` (query, `string`) - `created_before` (query, `string`) - `X-Connection-Id` (header, `string` required) — Selects which provider connection to use ```bash curl -X GET "https://api.oystara.com/v1/conversions?limit=25" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "X-Connection-Id: {connection_id}" ``` ### Get conversion `GET /v1/conversions/{id}` **Parameters** - `id` (path, `string` required) - `X-Connection-Id` (header, `string` required) ```bash curl -X GET "https://api.oystara.com/v1/conversions/{id}" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "X-Connection-Id: {connection_id}" ``` ## Commissions ### List commissions `GET /v1/commissions` **Parameters** - `limit` (query, `integer`) - `starting_after` (query, `string`) - `partner_id` (query, `string`) - `program_id` (query, `string`) - `include_remote_data` (query, `boolean`) - `created_after` (query, `string`) - `created_before` (query, `string`) - `X-Connection-Id` (header, `string` required) — Selects which provider connection to use ```bash curl -X GET "https://api.oystara.com/v1/commissions?limit=25" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "X-Connection-Id: {connection_id}" ``` ### Get commission `GET /v1/commissions/{id}` **Parameters** - `id` (path, `string` required) - `X-Connection-Id` (header, `string` required) ```bash curl -X GET "https://api.oystara.com/v1/commissions/{id}" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "X-Connection-Id: {connection_id}" ``` ## Connections ### List connections `GET /v1/connections` ```bash curl -X GET "https://api.oystara.com/v1/connections" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### Create connection `POST /v1/connections` **Request body** - `credentials` (`object` required) - `name` (`string`) - `program_id` (`string`) - `provider` (`string` required) ```bash 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" }' ``` ### Soft-delete connection `DELETE /v1/connections/{id}` **Parameters** - `id` (path, `string` required) ```bash curl -X DELETE "https://api.oystara.com/v1/connections/{id}" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### Get connection `GET /v1/connections/{id}` **Parameters** - `id` (path, `string` required) ```bash curl -X GET "https://api.oystara.com/v1/connections/{id}" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## Webhook Endpoints ### List outbound webhook endpoints `GET /v1/webhook-endpoints` ```bash curl -X GET "https://api.oystara.com/v1/webhook-endpoints" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### Create webhook endpoint `POST /v1/webhook-endpoints` **Request body** - `url` (`string` required) ```bash 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" }' ``` ### Soft-delete webhook endpoint `DELETE /v1/webhook-endpoints/{id}` **Parameters** - `id` (path, `string` required) ```bash curl -X DELETE "https://api.oystara.com/v1/webhook-endpoints/{id}" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## Ingest ### Inbound provider webhook `POST /v1/ingest/{provider}/{connection_id}` **Parameters** - `provider` (path, `string` required) - `connection_id` (path, `string` required) **Request body:** raw provider payload (`application/octet-stream`). ```bash curl -X POST "https://api.oystara.com/v1/ingest/rewardful/{connection_id}" \ -H "Content-Type: application/octet-stream" \ --data-binary @payload.bin ``` --- HTML version: https://oystara.com/docs/