API v1

Use this section when you call Cevoid's legacy REST API at https://api.cevoid.com/v1 directly. It covers API-specific behavior: authentication, rate limits, pagination, filtering, includes and errors. The reference lists the endpoints. For the Analytics SDK, MCP and other implementation guides, see the Developers overview, and for using Cevoid in the platform, see the Help Center.

Every API v1 endpoint requires an API key. Include it in the x-api-key header of each request.

1. Log in to your Cevoid account
2. Go to Settings → Integrations → Cevoid API⁠
3. Create an API key with the scopes your integration needs, and copy it when it is shown

A new key is shown only once, when you create it.

API v1 accepts two kinds of key:

• Scoped secret keys start with cev_sk_. They are the keys API v2 uses. On API v1, a scoped key needs posts:read for the post and inbox endpoints and members:read for GET /v1/members. The presets * and *:read include both, and the market endpoints need no scope. See Secret key scopes.
• Legacy v1 keys keep full v1 access until you revoke them. You can no longer create them: existing legacy keys are listed under Legacy keys on the same settings page, where you can revoke them. Legacy keys do not work with API v2.

Include your API key in the request headers using the x-api-key field:

curl https://api.cevoid.com/v1/posts \
  -H "x-api-key: YOUR_API_KEY"

• Store API keys as environment variables
• Use different API keys for development and production environments
• Rotate your API keys regularly
• Restrict API key access to only necessary team members

To ensure fair usage and keep the API stable for all users, API v1 enforces rate limits. When you exceed a limit, the API returns a 429 Too Many Requests response.

A request must pass every budget that applies to it. Requests served from a cache still count.

Responses include headers that help you monitor your usage. They follow the IETF RateLimit header fields:

When you exceed a limit, you receive a 429 status code with a plain-text body:

HTTP/1.1 429 Too Many Requests
content-type: text/plain; charset=utf-8
RateLimit-Limit: 400
RateLimit-Remaining: 0
RateLimit-Reset: 1
retry-after: 1

Rate limit exceeded

The retry-after header tells you how long to wait before retrying.

Check the RateLimit-Remaining header to slow down before you reach the limit:

const response = await fetch('https://api.cevoid.com/v1/posts', {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});

const remaining = response.headers.get('RateLimit-Remaining');

if (parseInt(remaining) < 2) {
  console.log('Low on requests. Slow down before the next request.');
}

Wait for the retry-after delay before you retry, and cap the number of attempts:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('retry-after') || '1');
      console.log(`Rate limited. Retrying in ${retryAfter} seconds...`);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    return response;
  }

  throw new Error('Max retries exceeded');
}

Reduce API calls by caching responses when possible:

const cache = new Map();
const CACHE_TTL = 60000; // 1 minute

async function getCachedPosts(galleryId) {
  const cacheKey = `posts-${galleryId}`;
  const cached = cache.get(cacheKey);

  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }

  const response = await fetch(`https://api.cevoid.com/v1/galleries/${galleryId}/posts`, {
    headers: { 'x-api-key': 'YOUR_API_KEY' }
  });

  const data = await response.json();
  cache.set(cacheKey, { data, timestamp: Date.now() });

  return data;
}

API v1 uses pagination to limit the data returned in a single request, which makes large datasets easier to work with. All endpoints that return multiple items support pagination.

A limit above 25 returns 400 with the body limit: less than or equal to 25.

curl -G https://api.cevoid.com/v1/posts \
  -H "x-api-key: YOUR_API_KEY" \
  -d skip=0 \
  -d limit=10

Change skip and limit to request another part of the result set:

curl -G https://api.cevoid.com/v1/posts \
  -H "x-api-key: YOUR_API_KEY" \
  -d skip=5 \
  -d limit=15

Paginated responses include metadata to navigate through the dataset:

{
  "count": 30,
  "next": "https://api.cevoid.com/v1/posts?skip=15&limit=10",
  "nodes": [
    {
      "id": "507f1f77bcf86cd799439011",
      // ... post data
    },
    {
      "id": "507f191e810c19729de860ea",
      // ... post data
    }
    // ... more items
  ]
}

• count: total number of items available
• next: URL for the next page of results, or null on the last page
• nodes: array containing the requested items

1. Start with the default limit: 25 items, which is also the maximum
2. Use the next URL: don't construct pagination URLs by hand
3. Handle empty results: check whether nodes is empty to detect the end of results
4. Respect rate limits: don't make requests too quickly when you page through large datasets

let skip = 0;
const limit = 25; // Use maximum for efficiency
let hasMoreData = true;

while (hasMoreData) {
  const response = await fetch(`https://api.cevoid.com/v1/posts?skip=${skip}&limit=${limit}`, {
    headers: {
      'x-api-key': 'YOUR_API_KEY'
    }
  });

  const data = await response.json();

  // Process the current batch
  data.nodes.forEach(post => {
    // Handle each post
  });

  // Check if there are more results
  hasMoreData = data.nodes.length === limit;
  skip += limit;
}

Filtering helps you retrieve specific subsets of data. Filters narrow down results based on criteria such as label associations. GET /v1/posts and GET /v1/products/{id}/posts accept a filter parameter.

Pass filters as a URL-encoded JSON string containing an array of filter objects. Each filter object must include three fields:

• type: the type of filter to apply. Only label is supported: it filters posts by their associated labels.
• operator: how to combine multiple values. OR returns posts matching any of the values, and AND returns posts matching all of them.
• values: array of IDs to filter by

curl -G https://api.cevoid.com/v1/posts \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'filter=[{"type":"label","operator":"OR","values":["507f1f77bcf86cd799439011"]}]'

Returns posts that have at least one of the specified labels:

curl -G https://api.cevoid.com/v1/posts \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'filter=[{"type":"label","operator":"OR","values":["507f1f77bcf86cd799439011","507f191e810c19729de860ea"]}]'

Returns posts that have all of the specified labels:

curl -G https://api.cevoid.com/v1/posts \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'filter=[{"type":"label","operator":"AND","values":["507f1f77bcf86cd799439011","507f191e810c19729de860ea"]}]'

To filter by label, you need each label's ID:

1. Log in to your Cevoid account
2. Go to Settings → Labels⁠
3. Find the label you want to filter by
4. Open the label's menu and choose Copy ID

Label IDs are 24-character hexadecimal strings. GET /v1/posts also returns the ID of each post's labels when you request include=labels. See Includes.

An invalid filter returns 400 with a plain-text body:

Use the include query parameter when you need related data alongside the resources you request. You get that data in the same response, and responses stay smaller when you do not need it.

Each endpoint's reference lists the relationships it supports and the fields they add. Includes are only available on endpoints that document the include parameter.

Pass include once, using a comma-separated list of supported relationship names. Whitespace around names is ignored; repeating a name does not duplicate the included data.

Unsupported names, empty values and repeated include query parameters return 400. Use only the names listed in the endpoint's reference.

Includes add related data to each returned resource. They do not change which resources match your request. When you omit include, you get the endpoint's default response.

The endpoint's response schema describes the included fields and what to expect when related data is unavailable.

Follow the response's next URL to keep includes on subsequent pages. See Pagination for the response format.

API v1 uses standard HTTP status codes to indicate the success or failure of your requests. A successful request returns 200 with a JSON body. An error returns a plain-text body that describes the problem, not JSON.

const response = await fetch('https://api.cevoid.com/v1/posts', {
  headers: {
    'x-api-key': 'YOUR_API_KEY'
  }
});

if (!response.ok) {
  const message = await response.text();
  console.error(`API Error (${response.status}):`, message);
  return;
}

const data = await response.json();

async function retryRequest(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.ok || response.status < 500) {
        return response; // Success or client error (don't retry)
      }

      if (attempt === maxRetries) {
        throw new Error(`Request failed after ${maxRetries} attempts`);
      }

      // Wait before retrying (exponential backoff)
      await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, attempt - 1)));

    } catch (error) {
      if (attempt === maxRetries) throw error;
    }
  }
}

if (!response.ok) {
  const message = await response.text();

  // Log the error with context
  console.error('API Request Failed:', {
    status: response.status,
    message,
    requestUrl: response.url,
    timestamp: new Date().toISOString()
  });
}

The reference is generated from the OpenAPI specification. Download it to generate a client or import the API into your HTTP tool.

• Posts: list posts, get a post, and list the posts of a gallery, product, collection, member or label
• Inbox: list pending submissions
• Markets: list markets and get a market
• Members: list members