# Cevoid API

> Read and write profiles, loyalty data, products, posts, orders and more with the versioned Cevoid REST API.

Breadcrumb: API › Overview · Updated: 2026-10-19
Docs index: https://docs.cevoid.com/developers/llms.txt

Use the Cevoid API to work with profiles, loyalty data, labels, products, posts, reviews, markets and orders from your own servers. It is a REST API over HTTPS that accepts and returns JSON.

If you are embedding widgets, tracking storefront analytics or connecting an AI client, see [Widget](https://docs.cevoid.com/developers/widget.md), the [Analytics SDK](https://docs.cevoid.com/developers/analytics-sdk.md) and [MCP](https://docs.cevoid.com/developers/mcp.md). If you use Cevoid in the platform, see the [Help Center](https://docs.cevoid.com/index.md).

## At a glance

| Topic | Details |
| --- | --- |
| Base URL | `https://api.cevoid.com/v2` |
| Authentication | Secret key as a bearer token, see [Authentication](https://docs.cevoid.com/developers/api/authentication.md) |
| Format | JSON request and response bodies |
| Pagination | Cursor-based, see [Pagination](https://docs.cevoid.com/developers/api/pagination.md) |
| Rate limits | 25 reads and 10 writes per second per workspace, see [Rate limits](https://docs.cevoid.com/developers/api/rate-limits.md) |

## Make your first request

Create a secret key in [Settings → Integrations → Cevoid API](https://app.cevoid.com/settings/integrations/api), store it in an environment variable, then call [`GET /v2/me`](https://docs.cevoid.com/developers/api/authentication/get-authentication-details.md) to check that it works:

```bash title="Verify your key"
export CEVOID_API_KEY="cev_sk_..."

curl https://api.cevoid.com/v2/me \
  -H "Authorization: Bearer ${CEVOID_API_KEY}"
```

The response describes the key, its workspace and its scopes:

```json title="200 OK"
{
  "data": {
    "id": "6f3ab66f14ebd9b9c67d1a31",
    "name": "Production integration",
    "type": "secret",
    "scopes": ["profiles:read", "orders:read"],
    "workspace": {
      "id": "6648c0f7bb9fd2d956fb0a42",
      "name": "Cevoid Demo"
    },
    "rate_limits": {
      "reads": 25,
      "writes": 10
    }
  }
}
```

## List resources

List endpoints return one page at a time. Pass `limit` (1 to 100) and send the `next_cursor` from each response back as `cursor` until `has_more` is `false`:

```bash title="List posts"
curl "https://api.cevoid.com/v2/posts?limit=25" \
  -H "Authorization: Bearer ${CEVOID_API_KEY}"
```

```json title="200 OK"
{
  "data": [],
  "has_more": true,
  "next_cursor": "eyJpZCI6InBvc3RfMDEifQ"
}
```

The same loop in TypeScript, with error handling:

```ts title="list-posts.ts"
const API_URL = "https://api.cevoid.com/v2"

type Page<T> = { data: T[]; has_more: boolean; next_cursor: string | null }

type ApiError = {
  status: number
  code: string
  message: string
  request_id: string
}

export async function listAllPosts(): Promise<unknown[]> {
  const posts: unknown[] = []
  let cursor: string | null = null

  do {
    const url = new URL(`${API_URL}/posts`)
    url.searchParams.set("limit", "100")
    if (cursor) url.searchParams.set("cursor", cursor)

    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.CEVOID_API_KEY}` },
    })

    if (!response.ok) {
      const error = (await response.json()) as ApiError
      throw new Error(`${error.code}: ${error.message} (${error.request_id})`)
    }

    const page = (await response.json()) as Page<unknown>
    posts.push(...page.data)
    cursor = page.has_more ? page.next_cursor : null
  } while (cursor)

  return posts
}
```

Keep every filter except `cursor` unchanged between page requests.

## Handle errors

Errors share one shape. Use the HTTP status for broad handling and `code` for specific recovery, and log `request_id` for every failed request:

```json title="422 Unprocessable Entity"
{
  "status": 422,
  "code": "validation_error",
  "message": "Request validation failed",
  "request_id": "req_abc123",
  "additional_data": {
    "errors": [
      {
        "field": "query.limit",
        "message": "Too big: expected number to be <=100"
      }
    ]
  }
}
```

> [!NOTE]
> Do not retry `401`, `403`, `404` or `422` responses until you change the request. Retry a `429` only after the `Retry-After` delay.

## Guides

- [Authentication](https://docs.cevoid.com/developers/api/authentication.md): authenticate with a secret key and verify its scopes.
- [Rate limits](https://docs.cevoid.com/developers/api/rate-limits.md): check limits and handle throttled requests.
- [Pagination](https://docs.cevoid.com/developers/api/pagination.md): retrieve the next page with a cursor.
- [Filtering](https://docs.cevoid.com/developers/api/filtering.md): narrow list results with query parameters.
- [Error handling](https://docs.cevoid.com/developers/api/errors.md): the error shape, status codes and common failure cases.
- [Debugging requests](https://docs.cevoid.com/developers/api/debugging-requests.md): reproduce failures and collect request IDs.

## Reviews

See the [product review](https://docs.cevoid.com/developers/api/reviews/list-product-reviews.md) and [company review](https://docs.cevoid.com/developers/api/reviews/list-company-reviews.md) references for filters, includes and localized response fields, and [review requests](https://docs.cevoid.com/developers/api/reviews/list-review-requests.md) for review invitations and their completion state. Import reviews from another platform with [`POST /v2/product-reviews`](https://docs.cevoid.com/developers/api/reviews/create-product-review.md) and [`POST /v2/company-reviews`](https://docs.cevoid.com/developers/api/reviews/create-company-review.md); both take an [`Idempotency-Key`](https://docs.cevoid.com/developers/api/idempotency.md).

## OpenAPI specification

The reference is generated from the [OpenAPI specification](https://docs.cevoid.com/developers/openapi/v2.json). Download it to generate a client or import the API into your HTTP tool.

**Recent changes**

- [Rotate API keys with a grace period](https://docs.cevoid.com/developers/changelog.md#2026-10-16-api-key-rotation) (Added, 2026-10-16): Rotating a secret API key creates a successor with the same name, scopes and owner, and keeps the old key working for 0, 1, 24 or 168 hours, so you can deploy the new secret without downtime.
- [API v1 endpoint limits are shared per workspace](https://docs.cevoid.com/developers/changelog.md#2026-10-11-api-v1-endpoint-limits) (Changed, 2026-10-11): On API v1, the inbox, single post and collection posts endpoints each allow 20 requests per second with bursts of up to 40, shared by all of a workspace's keys, so more keys no longer add capacity.
- [Full access and read-only presets for API keys and MCP connections](https://docs.cevoid.com/developers/changelog.md#2026-10-09-access-presets) (Added, 2026-10-09): API keys and MCP connections can be granted Full access (\*) or Read only (\*:read), which also cover scopes added later, and their access can now be edited instead of revoked and recreated.

[All API changes in the changelog](https://docs.cevoid.com/developers/changelog.md)

---

Canonical: https://docs.cevoid.com/developers/api