Read API
Authentication
Send your API key in the `Authorization` header on every request. That's the whole auth flow.
How it works
API key authentication
There is no handshake, no signing, and no refresh token. One API key in the `Authorization` header, every request, and you're in. The header value uses the HTTP-standard `Bearer <key>` form, but there is nothing else to build.
Keep your key safe
You see the full secret only once, right when you create it. Copy it straight into your secret manager or environment variables, and never commit it to source control.
Rotate when you need to
You can create a fresh key and revoke the old one any time from your account. Beta approval stays with your account, so you never need to go through the review process again.
Request headers
What you need to send
Every call to the search and detail endpoints needs this header.
Authorization
Bearer <api_key>
Required on every API request. Use the full API key you copied when creating it in your account. The word `Bearer` is just the HTTP prefix for API keys in this header, the actual key comes right after it.
Response headers
What you get back
Every response carries rate-limit and tracing headers. Read them instead of hard-coding delays, and your client will stay healthy even as we tune limits.
RateLimit-Policy
string
The policy your key is running under. Looks like `60;w=60, 1000;w=86400` (60 per minute, 1,000 per day).
RateLimit-Limit
string
The maximum requests allowed in the current window.
RateLimit-Remaining
string
How many requests you still have in the current window. Watch this to avoid hitting the limit.
RateLimit-Reset
string
Seconds until the current window resets and your quota refills.
Retry-After
string
Only sent with `429`. Wait this many seconds before retrying.
X-Request-Id
string (UUID)
A unique ID for this request. Copy it into any bug report so we can track it down quickly.
ETag
string
A fingerprint of the response for `GET /materials/{id}`. Send it back as `If-None-Match` to skip re-downloading data you already have.
Good to know
A few things to handle in your client
Build these rules into your integration once and you won't need to revisit them.
You only see published products
Search and detail only return products that are live on Acoustic Index. Anything unpublished or unknown comes back as `404 not_found`, so your client should treat that as a normal outcome.
Timestamps are UTC ISO 8601
Fields like `updated_at` and `expires_at` are always UTC ISO 8601 strings. Parse them as UTC and format them in the user's timezone yourself.
You see each key exactly once
When you create an API key, the full secret is shown on screen one time. After that only the safe prefix is visible, so copy the full key into your secret store immediately.
Pace your requests with the headers
Use `RateLimit-Remaining` and `RateLimit-Reset` from every response to decide when to slow down. That is much more reliable than hard-coded delays.
Errors always have the same shape
Every error comes back as `{ "error": "<code>", "message": "<explanation>" }`. Branch on `error` in your code and show `message` in logs so future-you can debug it.
Every response carries `X-Request-Id`
A unique UUID travels with every response. Drop it into your bug reports and we can find the exact request in our logs in seconds.