Getting Started

Quickstart

Create a key, build a draft order, launch it, and poll it to LIVE.

This walkthrough takes you from zero to a live placement using curl. Every request authenticates with the x-api-key header; tenant context is derived from the key, so there are no organization or workspace IDs to pass.

Replace cpk_your_key_here with a real key and https://api.respona.com if you are pointing at a different environment.

1. Create an API key

API keys are created in the Respona app under Settings → API Keys. Copy the raw key the moment it is shown — it is returned exactly once and cannot be retrieved again. Give it the FULL_ACCESS scope so it can both read and write. See Authentication for scopes, IP allowlists, and rotation.

2. Create a draft order with a placement

Orders are always created in DRAFT. Creating and editing a draft is free — you are only charged on launch.

$curl -X POST https://api.respona.com/rest/api/v1/orders \
>  -H "x-api-key: cpk_your_key_here" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "title": "Q3 link building",
>    "placements": [
>      {
>        "requested_url": "https://example.com/post",
>        "requested_anchor": "best widgets",
>        "quality_tier": "DR_40",
>        "content_guidelines": "Friendly, second-person tone. Mention our free trial.",
>        "domain_specifications": "US tech blogs, DR 40+, no casino/adult"
>      }
>    ]
>  }'

The 201 Created response is the full order object, including a server-assigned order_id, each placement’s placement_id, and the live price / price_breakdown. See Orders & Placements for the resource shape and the quality-tier table.

3. (Optional) Add or remove placements

While the order is still DRAFT you can add more placements…

$curl -X POST https://api.respona.com/rest/api/v1/orders/123/placements \
>  -H "x-api-key: cpk_your_key_here" \
>  -H "Content-Type: application/json" \
>  -d '{ "placements": [ { "requested_url": "https://example.com/blog", "requested_anchor": "widget guide", "quality_tier": "DR_30" } ] }'

…or remove one:

$curl -X DELETE https://api.respona.com/rest/api/v1/orders/123/placements/456 \
>  -H "x-api-key: cpk_your_key_here"

Both return the full, recomputed order object. Editing is rejected with 409 Conflict once the order has left DRAFT.

4. Launch the order

Launching charges credits and is the only endpoint that requires an Idempotency-Key — a unique value you generate per launch attempt. Retrying with the same key safely replays the original result instead of launching twice. See Idempotency.

$curl -X POST https://api.respona.com/rest/api/v1/orders/123/launch \
>  -H "x-api-key: cpk_your_key_here" \
>  -H "Idempotency-Key: 5f3c9a2e-1b7d-4e2a-9c8f-0a1b2c3d4e5f" \
>  -H "Content-Type: application/json"

A 200 OK returns the order (now LAUNCHED / IN_PROGRESS) with credits_charged and launched_at. If the charge would exceed your monthly credit limit you get 402 — see Credits & Billing.

5. Poll to LIVE

Placements progress asynchronously. Poll the order (or an individual placement) until it reaches a terminal state.

$curl https://api.respona.com/rest/api/v1/orders/123 \
>  -H "x-api-key: cpk_your_key_here"

Each placement walks a state machine ending in LIVE, REJECTED, or REFUNDED. For cadence and how to interpret terminal states, see Polling for Status.

Next steps