Getting Started

Introduction

The Respona Public API for creating, launching, and tracking link-placement orders.

The Respona Public API lets you programmatically create link-placement orders, add placements to them, launch them, and poll their progress — the same order flow available in the Respona app, exposed as a clean server-to-server REST surface.

  • Base URL: https://api.respona.com
  • Orders base path: /rest/api/v1/orders
  • Surface version: v1

This API is server-to-server only. Your API key is a secret — never embed it in a browser, mobile app, or any client a customer can inspect. See Authentication.

What you can do

The full endpoint-by-endpoint reference lives in the API Reference and is generated from the live OpenAPI contract. At a glance, the surface is six writes plus one status read:

ActionMethod & path
Create a draft order with placementsPOST /rest/api/v1/orders
Get an order (with live pricing)GET /rest/api/v1/orders/{order_id}
Add placements to a draft orderPOST /rest/api/v1/orders/{order_id}/placements
Remove a placement from a draft orderDELETE /rest/api/v1/orders/{order_id}/placements/{placement_id}
Delete a draft orderDELETE /rest/api/v1/orders/{order_id}
Launch an order (charges credits)POST /rest/api/v1/orders/{order_id}/launch
Get a single placement’s statusGET /rest/api/v1/orders/{order_id}/placements/{placement_id}

New to the API? Start with the Quickstart.

Conventions

These rules apply to every endpoint. They rarely change, so it’s worth reading them once.

  • JSON casing: all request and response fields are snake_case.
  • Timestamps: RFC 3339 / ISO 8601, always UTC with an offset — e.g. 2026-06-26T10:15:30Z. Never epoch, never local time.
  • Money: every monetary value is an integer amount in minor units (USD cents), e.g. price: 4200. The API is always USD.
  • Credits: 1 credit = 1 USD cent. Launch responses return both price (integer cents) and credits_charged (integer) so you can reconcile. See Credits & Billing.
  • Live pricing: every order and placement response includes the current price and price_breakdown, recomputed on every read, so you never have to trust a cached number.
  • Tenant context is implicit. Your organization and workspace are derived from the API key. You never send an organization or workspace ID, and none ever appears in a response.
  • Correlation: every response carries an X-Request-Id. It’s echoed if you supply one — include it in support requests.

Versioning & deprecation

The surface is versioned in the path (/rest/api/v1/...). Breaking changes ship under a new major version (/v2). When an endpoint or field is scheduled for removal, responses carry the standard Deprecation and Sunset headers (RFC 8594) with a documented minimum notice window before the surface is retired.

Webhooks

Not in v1. Placement progress is observed by polling. Signed, retried webhooks are planned for a future version.