Endpoints

The Hybiscus API has a few simple endpoints listed below. You can also view the auto-generated documentation which details the request and response schema in more detail at our API docs page. All the endpoints require authenetication via either the X-API-KEY header field, or passed as a query parameter string using the api_key parameter. See Authentication for more details.

POST - /api/v1/build-report

The build-report endpoint accepts HTTP POST requests, with a JSON body (application/json). This endpoint is used to provide the JSON for your report. The response from this endpoint is also JSON, returning the task_id and status of your task. For a detailed example, see the Creating a report page.

Example response

{
    "task_id": "d0cbbae7-a4b4-4b44-b348-c614ac418593",
    "status": "QUEUED"
}

Headers

Requests to this endpoint count against your quota which can be monitored via the headers returned from this response. The X-SINGLE-PAGE-REPORTS-REMAINING and the X-MULTI-PAGE-REPORTS-REMAINING headers provide this information with each request to this endpoint. Also, see the get-remaining-quota endpoint to access this information on demand.

POST - /api/v1/preview-report

The preview-report endpoint accepts HTTP POST requests, with a JSON body (application/json). This endpoint is similar to the build-report endpoint, except reports built here do not count against your monthly quota. This is because the file generated (accessible via the same get-report endpoint) are low quality, watermarked JPEG previews.

This endpoint is intended to be used to test your JSON to perfect the layout, before finalising it to use with the actual PDF report endpoint.

The response from this endpoint is also JSON, returning the task_id and status of your task, which can then be retrieved using the get-report endpoint.

This endpoint does not support uploading the generated preview to cloud storage.

GET - /api/v1/get-task-status

The get-task-status endpoint accepts HTTP GET requests. It can be used to check the status of your submitted task. To specify the task_id, it must be passed as query parameter in your URL.

Example

GET /api/v1/get-task-status?task_id=1d7ed978-5d1e-498c-ae17-62c7a7e7afe0&api_key=RakhHiNTtu5pmJ3IK8R2bUkbHjx-wd_BniNj-iEhAhc HTTP/1.1

{
    "status": "SUCCESS",
    "error_message": null
}

GET - /api/v1/get-report

The get-report endpoint accepts HTTP GET requests, and is used to retrieve your report. If you have enabled the cloud storage upload feature, your report will not be saved on the server, so you must access it at the URL provided.

GET - /api/v1/get-remaining-quota

The get-remaning-quota endpoint accepts HTTP GET requets and can be used to get your remaining quota on demand for single and multi-page reports (your quota depends on your current Plan). This information (excluding the period start and end points) is also provided in the headers of the build-report endpoint. The response content type is application/json.

Example response

{
    "remaining_single_page_reports": 92,
    "remaining_multi_page_reports": 0,
    "period_start": "2022-03-05T07:36:09",
    "period_end": "2022-04-05T07:36:09",
    "error": None
}