inceleAPI contract and reliability
Base URLs and versioning
Use https://api.incele.ai/v1 for authenticated external integrations. All published management operations require an account API key. “External” describes who may integrate; it does not mean anonymous access.
Swagger is generated from the same operation registry as the server. Download /openapi.json for client generation. The live API also serves /v1/openapi.json. Do not discover or depend on private dashboard, administration, billing control or internal storefront routes. Use the documented, authenticated /v1/workspaces/{workspaceId}/experience facade for customer-facing features.
The path version is v1. Additive fields can appear in responses; clients should tolerate unknown fields. Validation, available template fields and workspace policy still apply to all writes. The XYZ environment may contain changes not yet released to production.
Authentication and permissions
Create a named key in Integrations → Create API key. Select explicit permissions and an expiry from 1 to 365 days. Copy the secret once and store it in a backend secret manager. Send Authorization: Bearer <key> on every request. Keys expire independently of browser sessions; they do not have a refresh endpoint. Rotate by creating and verifying a replacement, then revoking the old key.
OAuth MCP connections have their own consent, audience and refresh-token lifecycle. An MCP access token cannot authenticate REST calls. A browser sign-in token is not the supported third-party API credential.
A key belongs to an account. Each workspace operation verifies current owner access to that workspace and its active status. Grant revocation, account restrictions and integration source blocking apply immediately. Scopes never grant platform administration or override workspace creation limits.
Requests and responses
Send JSON using Content-Type: application/json and UTF-8. Use Accept-Language when localized messages are useful; handle HTTP status and error codes rather than comparing translated text. JSON requests are limited to 5 MiB. Multipart upload accepts up to 12 files of 10 MiB each; JSON image upload permits 3 MiB decoded. Supported image MIME types are JPEG, PNG, WebP, GIF and AVIF. SVG and executable documents are rejected.
Management lists support resource-specific pagination and sorting. Use the returned pagination object; do not assume all list types have identical fields. Read the operation description before using optional filters. Account workspace lists also return the account creation policy.
For product creation and updates, names support 500 characters, brands 300, descriptions 100000 and information 500000, within the overall request limit. Unicode text is preserved. Most PUT operations expect the complete editable fields; website configuration updates support validated partial values.
Errors
| Status | Meaning | Client action |
|---|---|---|
| 400 | Invalid input or violated policy | Correct the request; do not retry unchanged |
| 401 | Missing, expired or revoked credential | Replace the credential or reconnect |
| 403 | Missing permission, ownership, or blocked access | Check scopes and current account/workspace access |
| 404 | Resource unavailable in the selected workspace | Verify workspace and resource IDs |
| 409 | Identity conflict or duplicate write | Fetch and reconcile |
| 413 | Request or upload too large | Reduce payload size |
| 429 | Rate limit exceeded | Honor Retry-After where present and use backoff |
| 5xx | Service failure | Retry reads with backoff; reconcile writes first |
Errors use a safe JSON message and may include a stable code. Internal database errors are not part of the public contract. Keep a safe record of the time, operation, HTTP status and environment for support; never send credentials or full OAuth callback URLs.
Rate limits and retries
Integration access is limited to 120 requests per minute per connection, with separate issuance/OAuth protections. Limit concurrency, use exponential backoff with jitter, and cache safe read responses in your own system. A rate-limit response may include Retry-After: 60.
A failed or interrupted connection does not prove that a write failed. Do not blindly repeat creation or deletion. Fetch the current resource and compare identifiers first. Product uniqueness constraints reject conflicting SKU, barcode and name values; these constraints do not replace end-to-end import reconciliation.
Support and disclosure
Use Contact us in the dashboard or [email protected] for integration questions or a privately reported security concern. Include a minimal reproduction with synthetic data. Do not publish secrets, other tenants' data or active attack payloads.