API FAQ
Frequently asked questions about the SPINES Public API.
Is the API free?
Yes. The free tier includes 1,000 read requests/day, 200 write requests/day, and 10 recognition credits/day. No credit card is required.
How do I get an API key?
Sign in to SPINES, go to Settings, enable Developer Mode, then navigate to the Developer tab to create an API key.
What is the difference between test and live keys?
Test keys (gtspn_test_...) return synthetic/mock data and never modify production data. Use them for development. Live keys (gtspn_live_...) access real data.
What are the rate limits?
30 requests per minute (burst), 1,000 reads per day, 200 writes per day. All limits are per-user, not per-key. Exceeding limits returns HTTP 429 with a Retry-After header.
How does pagination work?
All list endpoints use cursor-based pagination. The response includes a meta.next_cursor field. Pass it as ?cursor=... in your next request. Set ?limit=N (1-100) to control page size.
What scopes are available?
There are 12 scopes: read:collections, write:collections, read:books, read:categories, read:insights, read:personas, read:reading_lists, write:reading_lists, read:profile, write:profile, and recognize. Create keys with only the scopes your application needs.
How does book recognition work via the API?
POST a bookshelf image to /api/v1/recognize. You receive a job_id and poll_url. Poll the status endpoint until the job completes. Each recognition uses one daily credit (10/day). You can bring your own LLM key to bypass credits.
What is BYOK (Bring Your Own Key)?
For recognition, you can supply your own LLM API key via the X-LLM-Provider and X-LLM-API-Key headers. This bypasses daily credit limits. Supported providers: gemini, openai, anthropic.
What are book pairings?
Book pairings (part of Shelfology) show which books are commonly shelved together. Call GET /api/v1/books/{id}/pairings to see co-occurrence data.
Can I use the API for a commercial application?
Yes, within the API Terms of Service. You must not scrape data in bulk, circumvent rate limits, or build a direct competitor. Attribution ("Powered by SPINES") is appreciated.
Is there a webhook or real-time API?
Not currently. Recognition uses an async polling pattern. We may add webhooks in a future release.
How do I check API status and uptime?
Visit our status page at stats.uptimerobot.com/aTNz09s8Zz for real-time uptime monitoring. You can also call GET /api/v1/health for a programmatic health check.
How do I report an issue or request a feature?
Email support@getspines.com with your request. Include your API key prefix (never the full key) for account-specific issues.