# API 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](/swagger/) is generated from the same operation registry as the server. Download [/openapi.json](/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 [info@incele.ai](mailto:info@incele.ai) 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.