Admin API Conventions

These conventions apply to https://admin.mimeeqapi.com/v1. The Embed API retains its own request and response formats.

Authentication and Scopes

Send an Admin key in Authorization: Bearer <admin-key>. Each operation in the Admin API Reference declares its required scope. See the Authorization Guide for key creation and scope rules.

Responses

Successful resource responses put their payload in data. Single-resource operations return an object; list operations return an array. Pagination metadata appears beside data, under page.

Read fields from response.data rather than assuming that resource fields are at the top level. Use the reference's response schema for the operation you are calling.

Pagination

Paginated list operations accept:

Parameter	Description
limit	Page size, from 1 to 5,000. Default: 50.
cursor	Opaque continuation value returned by the previous response. Omit it for the first request.

Continue until page.nextCursor is null. Preserve the other query parameters across requests and URL-encode the cursor; do not parse or construct it yourself.

This server-side JavaScript example iterates over products:

async function* getProducts() {
  let cursor;

  do {
    const url = new URL('https://admin.mimeeqapi.com/v1/products');
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);

    const response = await fetch(url, {
      headers: {
        Authorization: `Bearer ${process.env.MIMEEQ_ADMIN_API_KEY}`,
        Accept: 'application/json',
      },
    });

    if (!response.ok) {
      throw new Error(`Product request failed (${response.status}): ${await response.text()}`);
    }

    const { data, page } = await response.json();
    yield* data;
    cursor = page.nextCursor;
  } while (cursor !== null);
}

for await (const product of getProducts()) {
  // Process each product on your server.
  console.log(product.productId);
}

Writes

Use the HTTP method and request body shown for the operation, with Content-Type: application/json. The JSON request-body limit is 4 MiB.

Write responses differ by resource. For example, catalog writes on collection sets, galleries, global option sets, product categories, and product groups return the resource after the write. Other operations return identifiers. Follow the response schema instead of assuming every write returns the same shape.

Bulk endpoints document their own limits and partial-failure behavior. Check their responses before retrying. After a timeout or connection failure during a write, verify the resulting state before sending it again.

Resource deletion is not exposed through the Admin API. Manage resource deletion in the Mimeeq app. Revoking an API key is a separate action in API Management.

Errors

Errors use this envelope:

{
  "code": "invalid_key",
  "message": "Invalid API key.",
  "requestId": "example-request-id"
}

Some errors include a details field with additional information, such as validation failures. Use the HTTP status and code for error handling; use message to understand the issue. Save requestId for support and log correlation.

Status	Typical cause	Next step
400	Invalid parameters or body	Correct the fields indicated by the response and operation schema.
401	Missing, malformed, unknown, expired, or revoked Admin key	Check the header, key, and environment.
403	Missing scope or a restricted operation	Check the operation's scope and resource restrictions.
404	Resource or route not found	Check the base URL and identifiers.
413	JSON request body exceeds 4 MiB	Reduce the payload or split supported bulk requests.
429	Request rate or monthly quota exceeded	Check rate_limit_exceeded or quota_exceeded and honor Retry-After. See Rate Limits.
500	Unexpected server error	Save the request ID and contact support if the failure persists.
503	Service temporarily unavailable (service_unavailable)	Retry later and honor Retry-After when present.

See Authentication Errors for specific auth codes and Requests Log for diagnostics.

Request Volume

Admin keys have a tier-based request-rate limit and monthly quota. Requests using the same key share both allowances across endpoints and clients. The monthly quota resets at the start of each UTC calendar month.

Read RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset when present. RateLimit-Limit reports burst capacity; RateLimit-Reset is the number of seconds until the bucket is full again. Both 429 error codes include Retry-After, but only rate_limit_exceeded includes the three RateLimit-* headers.

See Admin API Rate Limits for tier allowances, request counting, header examples, and retry guidance. Use pagination, supported bulk operations, and bounded concurrency for larger integrations.