# REST

Everything the SDKs do, done by hand. Use this page if your language has no SDK.

## What you must implement yourself

| Concern | What to do | Reference |
|---|---|---|
| Auth | bearer header on every request | authentication |
| Versioning | send `SciSpace-Version` | versioning |
| Idempotency | generate a UUID per POST, reuse it on retry | conventions |
| Retries | backoff with jitter on 429/5xx, honour `Retry-After` | errors-and-retries |
| Async | poll with backoff, or use webhooks | jobs |
| Pagination | follow `next_cursor` until `has_more` is false | conventions |
| Streaming | parse `text/event-stream`, handle partial frames | chats |

## A complete, correct request

Every header below is required except `Idempotency-Key`, which is required only for `POST`.

```bash
curl https://api.scispace.com/v1/searches \
  -H "Authorization: Bearer $SCISPACE_API_KEY" \
  -H "SciSpace-Version: 2026-08-01" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --fail-with-body \
  -d '{
    "query": "How does climate change affect biodiversity?",
    "depth": "standard"
  }'
```

```json
{
  "object": "search",
  "id": "srch_9dm2pq4x1a",
  "status": "queued",
  "created_at": "2026-08-11T09:14:22Z"
}
```

The response carries `202 Accepted`, not `200`. See first-request for the headers that come back
with it.

## A poll loop in bash

Poll the resource, not a separate status endpoint. Back off; do not spin.

```bash
id=$(curl -sS https://api.scispace.com/v1/searches \
  -H "Authorization: Bearer $SCISPACE_API_KEY" \
  -H "SciSpace-Version: 2026-08-01" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"query":"How does climate change affect biodiversity?","depth":"standard"}' \
  | jq -r .id)

delay=1
while :; do
  body=$(curl -sS "https://api.scispace.com/v1/searches/$id" \
    -H "Authorization: Bearer $SCISPACE_API_KEY" \
    -H "SciSpace-Version: 2026-08-01")
  status=$(printf '%s' "$body" | jq -r .status)
  case "$status" in
    succeeded) printf '%s' "$body" | jq -r .answer.text; break ;;
    failed)    printf '%s' "$body" | jq -r .error.message >&2; exit 1 ;;
  esac
  sleep "$delay"
  delay=$(( delay * 2 > 30 ? 30 : delay * 2 ))
done
```

## Related

conventions · sdks-overview