# Using the API

Source: https://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"
  }
}
```