# External API guide

## Create a key

Open the dashboard sidebar **Integrations**, choose a name, explicit permissions and expiration (1–365 days). Copy the key immediately: it is shown once. Keys belong to your account and can be revoked from any workspace.

Store write keys on your server. Never place them in public JavaScript, a mobile application binary, a repository, a URL or a browser analytics event. For a public website or mobile application, keep the integration key in your backend and return only the data your application should expose.

## Authentication and tenants

Send `Authorization: Bearer YOUR_KEY`. API keys work at `/v1`; MCP OAuth tokens work at `/mcp`. Tokens are resource-bound and cannot be interchanged.

```sh
curl https://api.incele.ai/v1/workspaces \
  -H 'Authorization: Bearer YOUR_KEY'
```

Use an owned workspace ID from that response:

```sh
curl https://api.incele.ai/v1/workspaces/WORKSPACE_ID/products \
  -H 'Authorization: Bearer YOUR_KEY'
```

Existing flat resource URLs also accept `?workspaceId=WORKSPACE_ID` or the `X-Workspace-Id` header. New clients should use explicit workspace paths. Account endpoints do not accept a workspace selector.

## Create a product

```sh
curl -X POST https://api.incele.ai/v1/workspaces/WORKSPACE_ID/products \
  -H 'Authorization: Bearer YOUR_KEY' -H 'Content-Type: application/json' \
  --data '{"name":"Kore Leke Karşıtı Tonik","brand":"celleanser","sku":"TY-793984714","barcode":"UNVERIFIED-TY-793984714","stock":0,"status":"INACTIVE","description":"Türkçe ürün açıklaması","information":"Imported listing; details unverified.","imageIds":[],"tagIds":[],"sales":[]}'
```

Names support Unicode and up to 500 characters, brands up to 300, descriptions up to 100000, and information up to 500000, subject to the complete request size limit. The API does not verify a seller's claims. Keep unverified products inactive until reviewed.

SKU, barcode and name must satisfy existing per-workspace uniqueness rules. Product slugs are globally unique; normalized slug collisions receive a stable suffix. Writes use parameterized SQL. Concurrent duplicates return conflicts rather than creating extra rows.

## Operations

The [generated reference](/api/) lists every endpoint, scope and complete MCP input schema. Resources include products, collections, tags, media, website settings and account/workspace management. Use GET before PUT: most resource updates require the full current editable fields. Website updates support validated partial configuration updates.

List endpoints accept supported filters and pagination (`page`, `pageSize`). Responses contain pagination for existing catalogue lists. Account workspace lists return their page/pageSize and creation policy. Do not assume one page includes all resources.

For multipart media, use `POST /v1/workspaces/WORKSPACE_ID/media/upload` with image files in the `files` field (maximum 12 files, each within the existing media limit). JSON media tools accept base64 images up to 3 MiB decoded. Uploaded IDs belong to their workspace and cannot be reused across accounts.

## Errors and retries

- 400: invalid input, missing workspace ID, unavailable subdomain or creation policy violation.
- 401: missing, expired or revoked token.
- 403: missing scope, inactive account/workspace, lost ownership or globally blocked source.
- 404: resource not found in the selected workspace.
- 409: duplicate identity or conflicting concurrent write.
- 429: rate limit; wait at least the returned retry interval.
- 5xx: unexpected failure; internal database details are hidden.

Integration requests are limited to 120 per minute per connection, with additional OAuth/issuance limits. Do not blindly replay non-idempotent writes after an interrupted response: first check whether the intended resource exists. Product identity constraints help detect duplicate requests; they do not replace application-level reconciliation.

Administrative source blocking stops all connections for that source, including existing access tokens and refreshes. Unblocking restores unrevoked, unexpired connections. Users can revoke their own connections separately.