Bypass Censorship API¶
Introduction¶
The Bypass Censorship API allows publishers to interact with the Bypass Censorship platform and to obtain short links, snapshot links, and mirror links for their content.
Note
This documentation is generic and applies to any deployment of the Bypass Censorship platform. For the base URL and authentication details specific to your use, contact your vendor.
The API supports the following endpoints:
Endpoint |
Method |
Description |
|---|---|---|
/me |
GET |
Retrieve information about the authenticated user’s pool. |
/link |
GET |
Generate a short link or a direct mirror link. |
/<hash> |
GET |
Redirect to the live mirror associated with the given hash. |
Authentication¶
The API endpoints are protected by authentication. The authentication method depends on the endpoint:
/me endpoint: The API key is provided in the request arguments using the key parameter. If no API key is provided, the “public” resource pool is used.
/link endpoint: The API key is provided in the request arguments using the key parameter. If no API key is provided, the “public” resource pool is used.
Endpoints¶
/me¶
Retrieve information about the authenticated user’s pool.
Method: GET
URL: /me
Query Parameters:
key (optional): The API key of the pool. If not provided, the public API key is used.
Response:
Success: Returns the information about the pool in JSON format.
Failure: Returns a 403 response if the API key is invalid.
/link¶
Generate a circumvention link for a specific resource. This may create a new link or return an already existing link if it has been previously created.
Method: GET
URL: /link
Query Parameters:
url (required): The URL for which a circumvention link needs to be generated.
type (optional): The type of link to generate. Valid values are “live”, “short”, or “snapshot”. If not provided, “direct” is used.
key (optional): The API key of the pool. If not provided, the public API key is used.
expiry (optional): The duration that a snapshot will remain published for. Valid values are “long” and “short”. If not provided, “short” is used.
footer_text (optional): Defines the footer text to be used when publishing a snapshot.
footer_link (optional): Defines the footer link to be used when publishing a snapshot.
When footer_text is not specified, no footer link will be added to a snapshot. When footer_link is not specified, but footer text is specified, a link will be added to a live mirror of the snapshotted article.
When type is specified as “snapshot” and a private API key is specified, a request will be made to the resource to check the status code returned. If the status code is not 200 and a snapshot had previously been published then that snapshot will be deleted and future attempts to access it will fail. This mechanism may be used by publishers to perform self-service take downs of unwanted snapshots.
Response:
Success: Returns the generated link in JSON format.
Failure: Returns a 403 response if the resource is not on a supported domain.
Failure: Returns a 404 response if no live mirror exists for the resource.
Failure: Returns a 500 response if it was not possible to generate a snapshot for a resource.
/<hash>¶
Redirect to the live mirror associated with the given hash.
Method: GET
URL: /<hash>
Path Parameters:
hash (required): The hash associated with the short link.
Query Parameters:
force (optional): Always redirect to a mirror and ignore GeoIP information.
force_ip (optional): Override the client IP address and base the GeoIP lookup on this IP address instead.
Response:
Success: Redirects the client to the original URL.
Failure: Returns a 404 response if the hash is invalid or not found.
Example Usage¶
$ curl -X GET /me?key=<api_key>
$ curl -X GET /link?url=<url>&type=<type>&key=<api_key>
$ curl -X GET /<hash>
Note: Replace <api_key>, <url>, <type>, and <hash_> with actual values.
Authentication and Permissions¶
The API endpoints require valid API keys for authentication. The API key can be obtained from the pool configuration.
API keys have different permissions:
Public API Key: Can be used to access live mirror links, snapshots, and resolve short links.
Private API Key: Can be used to access live mirror links, snapshots, and create new short links.
Response Format¶
The API endpoints return JSON responses. Successful responses contain the requested data, while failure responses provide relevant error messages.
Error Handling¶
In case of errors, the API endpoints return appropriate HTTP status codes and error messages. Clients should handle these errors gracefully and take appropriate actions.