# Using the API

Source: https://preview.ceyo.ai/docs/signal/using-the-api

### API conventions

**JSON**

Request and response bodies use `application/json`.

**Identifiers**

Resource IDs are UUIDs. Project and location paths also accept configured external IDs.

**Dates**

Dates use `YYYY-MM-DD`. Timestamps use ISO 8601 in UTC.

**Pagination**

List endpoints use `page` and `per_page` and return a `pagination` object.

**Idempotency**

Endpoints that support safe retries accept an `Idempotency-Key` header.

### Site Audit IP allowlisting

Site Audit sends crawler requests from a stable production egress IP. If your firewall or bot protection restricts automated traffic, allowlist this address for `GET` and `HEAD` requests.

**Production IP**

`34.248.152.92`

**User agent**

`CeyoSiteAudit/1.0 (+https://www.ceyo.ai/features/site-audit)`

### Rate limits

Standard public API traffic is limited to 600 requests per minute per API key. Source-IP limits and lower limits for sensitive or write-heavy operations may also apply.

When a limit is reached, the API returns `429 Too Many Requests`. Wait for the number of seconds in the `Retry-After` header before retrying. Use exponential backoff and reuse the same `Idempotency-Key` when retrying an idempotent operation.

```
HTTP/1.1 429 Too Many Requests
Retry-After: 42

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests were made.",
    "details": null,
    "request_id": "req_01K1F8M7QX4R2V9N6Y3Z0A5BCT"
  }
}
```

### Errors

Every error uses one nested `error` envelope containing a stable code, readable message, details, and request identifier. `details` is always an object, array, or null.

```
{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "details": null,
    "request_id": "req_01K1F8M7QX4R2V9N6Y3Z0A5BCT"
  }
}
```

#### Model availability

Unsupported model and country combinations return `422 unsupported_model_country_combination`, with the unsupported model keys in `details`. If availability cannot be verified, the API returns `503 capability_validation_unavailable`; retry later without changing the request.

### Sandbox access

An integration sandbox with synthetic provider responses is available on request for testing API and embed integrations. Contact Ceyo to request access. Sandbox data is not suitable for production use.