To get started using the REST API, you can generate an API key for your user in the Admin Web UI:
http://127.0.0.1:8000/admin/api/apitoken/add/
or by calling the http://127.0.0.1:8000/api/v1/auth/get_api_token endpoint with a username & password:
curl -X 'POST' \ 'http://127.0.0.1:8000/api/v1/auth/get_api_token' \ -H 'Content-Type: application/json' -d '{"username": "YOURUSERNAMEHERE", "password": "YOURPASSWORDHERE"}'Tip
Bearer Tokens are the recommended method for the best balance of security and convenience.
Pass Authorization=Bearer YOURAPITOKENHERE as a request header.
curl -X 'GET' \ 'http://127.0.0.1:8000/api/v1/core/snapshots?limit=10' \ -H 'accept: application/json' \ -H 'Authorization: Bearer YOURAPITOKENHERE'This method is provided in case you have a reverse proxy in front of ArchiveBox that consumes the bearer header.
Pass X-ArchiveBox-API-Key=YOURAPITOKENHERE as a request header.
curl -X 'GET' \ 'http://127.0.0.1:8000/api/v1/core/snapshots?limit=10' \ -H 'accept: application/json' \ -H 'X-ArchiveBox-API-Key: YOURAPITOKENHERE'Warning
This method is sometimes known as "Capability URLs" because anyone in possession of the URL can perform API actions. It comes with important security caveats and is not recommended unless you fully understand the risks.
Pass api_key=YOURAPITOKENHERE as a GET/POST query parameter.
curl -X 'GET' \ 'http://127.0.0.1:8000/api/v1/core/snapshots?limit=10&api_key=YOURAPITOKENHERE' \ -H 'accept: application/json'Caution
We recommend sticking to header-based authentication and not using this method unless you deeply understand the CSRF/CORS security risks.
This method is mostly useful when accessing the API from external apps where CSRF/CORS is not a concern (e.g. curl, mobile apps, other servers, etc.).
Browsers enforce that requests made to the ArchiveBox API from other origins will not include any session cookies by default. This is is a foundational security principle of the web that protects you from API requests being initiated by JS on websites you don't control (aka CSRF/CORS attacks).
To allow incoming POST/PUT/DELETE requests from other domains that you trust, you must add them to
CSRF_TRUSTED_ORIGINSin thearchivebox/core/settings.pysource code on your machine (open an issue and explain your use-case for help).
Log in via the Admin Web UI: /admin/login/, you can then re-use your login session id (stored in the sessionid cookie) for REST API requests. By default, this only allows you to make requests from the same domain ArchiveBox is being served on (e.g. from browser devtools open on an ArchiveBox page or CLI tools).
curl -X 'GET' \ 'http://127.0.0.1:8000/api/v1/core/snapshots?limit=10' \ -H 'accept: application/json' \ -H 'Cookie: sessionid=YOURSESSIONIDVALUEHERE'Caution
This method is fairly uncommon and is only useful in a few niche situations where the other methods are not available.
We will likely remove this method in a future ArchiveBox release if nobody uses it.
If you rely on this method and want us to keep it, please open an issue and explain your use-case!
Pass your ArchiveBox admin username & password via HTTP Basic Authentication.
curl -X 'GET' \ 'http://127.0.0.1:8000/api/v1/core/snapshots?limit=10' \ -u 'YOURUSERNAMEHERE:YOURPASSWORDHERE' -H 'accept: application/json'