> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vantr.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API conventions

> Understand base URLs, auth headers, pagination, response envelopes, and archive behavior.

# API conventions

The v2 API uses scoped credentials, JSON request bodies, predictable response envelopes, and offset pagination where list endpoints support it.

## Base URLs

Vantr uses separate hosts for the public site, the signed-in web app, and API traffic.

| Surface          | URL                              |
| ---------------- | -------------------------------- |
| Marketing site   | `https://vantr.ai`               |
| Web application  | `https://app.vantr.ai`           |
| Developer portal | `https://api.vantr.ai/developer` |
| Developer docs   | `https://api.vantr.ai/docs`      |
| API endpoint     | `https://api.vantr.ai`           |

<Tabs>
  <Tab title="Production" icon="cloud">
    ```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
    https://api.vantr.ai
    ```
  </Tab>

  <Tab title="Local development" icon="laptop">
    ```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
    http://localhost:8080
    ```
  </Tab>
</Tabs>

The Vantr app calls the business/application API under `/v1`. Third-party integrations use the developer API under `/v2`. API-only users can manage apps, credentials, OAuth consent, docs, and v2 traffic from `api.vantr.ai`.

## Authentication headers

Most server-to-server integrations use Basic auth. OAuth integrations use bearer tokens.

<CodeGroup>
  ```bash Basic auth theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -u "$CLIENT_ID:$CLIENT_SECRET" \
    "https://api.vantr.ai/v2/products?limit=25"
  ```

  ```bash Client headers theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl \
    -H "x-client-id: $CLIENT_ID" \
    -H "x-client-secret: $CLIENT_SECRET" \
    "https://api.vantr.ai/v2/products?limit=25"
  ```

  ```bash Bearer token theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -H "Authorization: Bearer $ACCESS_TOKEN" \
    "https://api.vantr.ai/v2/products?limit=25"
  ```
</CodeGroup>

## Request bodies

Write endpoints accept JSON. Use snake\_case field names exactly as they appear in the OpenAPI reference.

<ParamField body="name" type="string" required>
  Human-readable product or category name.
</ParamField>

<ParamField body="category_id" type="string | null">
  UUID of the category to assign to a product. Use `null` to leave the product uncategorized.
</ParamField>

<ParamField body="variations" type="object[]" required>
  One or more product variations when creating a product.
</ParamField>

## List pagination

List endpoints that support pagination use `limit` and `offset`.

<ParamField query="limit" type="integer" default="50">
  Number of records to return. Endpoints that define `maximum` currently cap this at `100`.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of records to skip before returning the next page.
</ParamField>

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -u "$CLIENT_ID:$CLIENT_SECRET" \
  "https://api.vantr.ai/v2/products?limit=50&offset=100"
```

<ResponseField name="pagination" type="object">
  Pagination metadata returned by paginated list endpoints.

  <Expandable title="pagination fields">
    <ResponseField name="limit" type="integer">
      Number of records requested.
    </ResponseField>

    <ResponseField name="offset" type="integer">
      Number of records skipped.
    </ResponseField>

    <ResponseField name="total" type="integer">
      Total records matching the query.
    </ResponseField>
  </Expandable>
</ResponseField>

## Response envelopes

Read endpoints return a `success` boolean with resource-specific fields.

<Columns cols={3}>
  <Card title="List locations" icon="map-pin" horizontal>
    `success`, `locations`, `pagination`
  </Card>

  <Card title="List products" icon="package" horizontal>
    `success`, `products`, `pagination`
  </Card>

  <Card title="Capabilities" icon="waypoints" horizontal>
    `success`, `capabilities`
  </Card>
</Columns>

## Archive and deactivate behavior

Delete-style endpoints use domain-safe status changes:

<Columns cols={2}>
  <Card title="Products and categories" icon="archive" horizontal>
    Archive records so catalog history can stay connected.
  </Card>

  <Card title="Vendors" icon="user-minus" horizontal>
    Deactivate vendor profiles instead of removing vendor history.
  </Card>
</Columns>

<Tip>
  Prefer explicit update calls when you need to change fields. Use archive or deactivate calls when the record should no longer appear in normal active lists.
</Tip>