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.

cURL

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.

cURL

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

conventions · sdks-overview

Last updated 2026-08-10

What you must implement yourself

A complete, correct request

A poll loop in bash

Related