# Conventions

Everything true of every endpoint. Resource pages link here instead of restating it.

## Request headers

| Header | Required | Notes |
|---|---|---|
| `Authorization: Bearer …` | yes | authentication |
| `SciSpace-Version` | recommended | pins behaviour; versioning |
| `Idempotency-Key` | on POSTs | 24h replay window |
| `Content-Type: application/json` | on POSTs | |

## Response headers

| Header | Meaning |
|---|---|
| `X-Request-Id` | quote this in support requests |
| `X-RateLimit-Limit` / `-Remaining` / `-Reset` | rate-limit |
| `X-Credits-Cost` / `X-Credits-Remaining` | credit |

## Object envelope

Every object has `object`, `id`, `created_at`. Every list:

```json
{
  "object": "list",
  "data": [
    {
      "object": "search",
      "id": "srch_9dm2pq4x1a",
      "status": "succeeded",
      "depth": "standard",
      "paper_count": 20,
      "credits_cost": 5,
      "created_at": "2026-08-11T09:14:22Z"
    },
    {
      "object": "search",
      "id": "srch_7bk1lm5z3c",
      "status": "succeeded",
      "depth": "standard",
      "paper_count": 20,
      "credits_cost": 5,
      "created_at": "2026-08-11T08:02:51Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJvIjoyMH0"
}
```

## Pagination

`limit` (1–100, default 20) and `cursor`. Cursors, not page numbers — ranked results are not stable
across requests, so offsets would silently skip or duplicate items.

## Expanding nested objects

`expand[]=citations.source` hydrates references in one round trip. Expandable paths are listed on
each resource page.

## Idempotency

Send a unique `Idempotency-Key` on every POST. A replay within 24h returns the original response
without re-charging credits. Required for anything metered.

## Timestamps, enums, nulls

RFC 3339 UTC, `_at` suffixed. Enums are lower_snake_case strings. A field that could not be
determined is `null` — never an empty string, never a guess.

## Related

errors-and-retries · job · versioning