API documentation · 2 of 9
Authentication
Every request carries an API key. Keys belong to your account and reach only your own projects.
Create a key
- Sign in and open Account → API keys.
- Give the key a name you will recognise later, such as the script that uses it.
- Tick Allow this key to modify data if it will create projects, change settings or start crawls.
- Copy the key when it appears. It is shown once: only a hash is stored, so it cannot be shown again. If it is lost, revoke it and create another.
Scopes
| Scope | Allows |
|---|---|
| read | Every GET: projects, crawls and results. Every key has it. |
| write | Creating projects, changing their settings, and starting and stopping crawls. |
Send it
As a bearer token in the Authorization header:
curl -H "Authorization: Bearer sk_live_..." http://localhost:9000/api/v1/projectsWhen it is refused
| Status | Code | Why |
|---|---|---|
401 | missing_credentials | No bearer token was sent. |
401 | invalid_credentials | The key is unknown, malformed or revoked. All three answer alike. |
403 | insufficient_scope | A read-only key called an endpoint that needs write. |
404 | project_not_found | The project is not yours. It is not found rather than forbidden, so the API never confirms an id exists. |
Revoking a key in Account → API keys takes effect at once. The page also shows when each key was last used.