> 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.

# Quickstart

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.

> **Note**
>
> 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](/guides/getting-started/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](/guides/core-concepts/credits-billing).

```bash
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](/guides/core-concepts//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…

```bash
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:

```bash
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](/guides/api-conventions/idempotency).

```bash
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](/guides/core-concepts/credits-billing).

## 5. Poll to LIVE

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

```bash
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](/guides/core-concepts/polling-for-status).

## Next steps

* [Authentication](/guides/getting-started/authentication) - key formats, scopes, IP allowlists, and rotation.
* [Credits & Billing](/guides/core-concepts/credits-billing) - pricing modifiers and the monthly credit pool.
* [Errors](/guides/api-conventions/errors) - the error envelope and status codes.
* [API Reference](/api-reference) - the full generated endpoint reference.