> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.respona.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.respona.com/_mcp/server.

# Introduction

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`

> **Note**
>
> 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](/guides/getting-started/authentication).

## What you can do

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

| Action                                | Method & path                                                     |
| ------------------------------------- | ----------------------------------------------------------------- |
| Create a draft order with placements  | `POST /rest/api/v1/orders`                                        |
| Get an order (with live pricing)      | `GET /rest/api/v1/orders/{order_id}`                              |
| Add placements to a draft order       | `POST /rest/api/v1/orders/{order_id}/placements`                  |
| Remove a placement from a draft order | `DELETE /rest/api/v1/orders/{order_id}/placements/{placement_id}` |
| Delete a draft order                  | `DELETE /rest/api/v1/orders/{order_id}`                           |
| Launch an order (charges credits)     | `POST /rest/api/v1/orders/{order_id}/launch`                      |
| Get a single placement's status       | `GET /rest/api/v1/orders/{order_id}/placements/{placement_id}`    |

New to the API? Start with the **[Quickstart](/guides/getting-started/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](/guides/core-concepts/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](/guides/core-concepts/polling-for-status). Signed, retried webhooks are planned for a
future version.