What the Content API does, how to authenticate, rate limits and common conventions.
The Content API lets you manage your Optimove Content Studio content over REST. Today it covers blocks, which are reusable pieces of content you can insert into templates. More content types will be added over time.
Base URLs
Use the base URL for the region your Optimove account is hosted in.
EU: https://api5.optimove.net/content/v1
US: https://api4.optimove.net/content/v1
Authentication
Every request must include an Optimove API key in the X-API-KEY header. The key must have the admin role. Each key belongs to one tenant, so a request can only read and change that tenant's content.
If the header is missing or the key is not valid, the API returns 401 Unauthorized. If the key doesn't have the admin role, the API returns 403 Forbidden.
Rate limits
Requests are rate limited per tenant. Allowed rate - 4000 requests/min.
Every response includes these headers:x-ratelimit-limit: the number of requests allowed in the current window.x-ratelimit-remaining: the number of requests left in the current window.
When the limit is reached, the API returns 429 Too Many Requests. Wait until the limit resets, then retry. We recommend retrying with exponential backoff and keeping request rates steady rather than sending bursts.
Errors
Errors use standard HTTP status codes. The response body contains an errors list with one or more messages that explain what went wrong, for example:
{"errors": ["Content block with id 3fa85f64-5717-4562-b3fc-2c963f66afa6 not found"]}400 Bad Request: the request is not valid. The messages say which fields to fix.401 Unauthorized: the API key is missing or not valid.403 Forbidden: the API key doesn't have the admin role, or the tenant isn't allowed to change this item.404 Not Found: the item doesn't exist.409 Conflict: another item already uses the same name or tag name.422 Unprocessable Entity: the request is valid but can't be processed, for example deleting a block that templates still use.429 Too Many Requests: the rate limit is reached.500 Internal Server Error: an unexpected error. Retry later.