## Introduction

DrillPlan's [Reporting API](/solutions/drillplan/apis/reportingapi) provides access to reports created in DrillPlan.

## How to get project reports

A project ID needs to be provided to enumerate reports. A project ID can be obtained by listing user-joined projects using the `/drillplan/plan/v1/projects/joined` end-point exposed as part of [Project Plan API](/solutions/drillplan/apis/projectplanapi). After obtaining a project ID, the reports created in that project can be retrieved by executing a GET request using `/drillplan/reporting/v2/projects/{projectId}/reports` end-point.

## Asynchronous Reporting API

Such tasks as report creation, report update, and report export implemented as asynchronous processes and requires several HTTP calls to the [Reporting API](/solutions/drillplan/apis/reportingapi) to be completed.

### How to create a report

1. An asynchronous task for creating a report can be created via executing a POST using `/drillplan/reporting/v2/projects/{projectId}/reports/create` end-point and providing the following payload:

```json
{ 
   "name": "New report name", 
   "template": "Template name",
   "callback": {
     "uri": "https://example.com/callback",
     "headers": {
         "Authorization": "Bearer your_token_here",
         "Custom-Header": "custom_header_value"
     }
   }
}
```
Available report templates could be obtained via executing a GET request using `/drillplan/reporting/v2/templates` end-point.
2. Once the report creation is complete, the DrillPlan Reporting subsystem will send a POST request to the specified callback endpoint with the following payload:

```json
{
  "id": "395849cf9bbf440d91", // ID of the task the callback is related to.
  "status": "Succeeded", // The task execution status.
  "artifacts": {
     "report_id": "ac5ed2e4e05976" // The created report ID.
  }
}
```
3. You can also retrieve the tasks created in step 1 by sending a GET request to `/drillplan/reporting/v2/projects/{projectId}/tasks/{taskId}`.
4. After obtaining the `report_id`, you can get the result of the report creation by sending a GET request to `/drillplan/reporting/v2/projects/{projectId}/reports/{reportId}`.


### How to update a report

1. An asynchronous task for updating a report can be created via executing a POST using `/drillplan/reporting/v2/projects/{projectId}/reports/{reportId/content/update` end-point and providing the following payload:

```json
{ 
    // Optional 
    // "chapters": [ 
    //    { 
    //        "id": 123412 
    //    } 
    //] 
    "callback": {
       "uri": "https://example.com/callback",
       "headers": {
          "Authorization": "Bearer your_token_here",
          "Custom-Header": "custom_header_value"
       }
    }
}
```
Where the `chapters` field contains a list of chapters that needed to be updated. The `chapters` field is optional and if not provided, all report chapters are updated.
2. Once the report update is complete, the DrillPlan Reporting subsystem will send a POST request to the specified callback endpoint with the following payload:

```json
{
  "id": "395849cf9bbf440d91", // ID of the task the callback is related to.
  "status": "Succeeded", // The task execution status.
}
```
3. You can also retrieve the tasks created in step 1 by sending a GET request to `/drillplan/reporting/v2/projects/{projectId}/tasks/{taskId}`.


## How to export a report

1. An asynchronous task for exporting a report should be created by executing a POST request using `/drillplan/reporting/v2/projects/{projectId}/reports/{reportId}/content/export` end-point.
The payload provided in the request should contain the required content type of the exported report, e.g.:

```json
{ 
    "content_type": "application/pdf",
    "callback": {
       "uri": "https://example.com/callback",
       "headers": {
          "Authorization": "Bearer your_token_here",
          "Custom-Header": "custom_header_value"
       }
    }       
}
```
Successful responses to such task creation requests contain a task ID that can be used to monitor the task state.
2. Once the report export is complete, the DrillPlan Reporting subsystem will send a POST request to the specified callback endpoint with the following payload:

```json
{
  "id": "395849cf9bbf440d91", // ID of the task the callback is related to.
  "status": "Succeeded", // The task execution status.
  "artifacts": {
     "export_id": "ac5ed2e4e05976"
  }
}
```
3. You can also retrieve the tasks created in step 1 by sending a GET request to `/drillplan/reporting/v2/projects/{projectId}/tasks/{taskId}`.
4. After obtaining the `export_id`, the result of the export operation can be received by issuing a GET request to `/drillplan/reporting/v2/projects/{projectId}/exports/{exportId}`. Successful responses to such requests should contain binary data of the requested media type.


**🚩Important:** *In cases where a report update is in progress, attempts to create an export task should fail with HTTP status code 423 (Locked). After some time has passed, the request can be re-issued.*