---
title: "Depot reportdefinitions"
description: "Every reportdefinitions operation in the Depot API, with parameters, responses and code samples in six languages."
url: "https://support.outpostplatform.com/api/generated/depot/reportdefinitions/"
product: "depot"
type: "reference"
status: "reviewed"
last_reviewed: 2026-11-06
source: "https://gitlab.com/outpostplatform/docs/-/edit/main/src/content/docs/api/generated/depot/reportdefinitions.mdx"
license: "CC BY 4.0"
---

# Depot reportdefinitions

Registers the definition library on the TENANT mux.

This page is generated from the Depot route table. Every operation carries the permission it needs and the anchor an agent can link to.

### GET `/api/v1/reports/definitions` {#depot.reportdefinitions.listReportDefinitions}

**List report definitions**

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `dir` | query | string, one of asc, desc | No | Sort direction. |
| `page` | query | integer | No | One-based page number. Defaults to 1. |
| `pageSize` | query | integer | No | Rows per page, 1 to 200. Defaults to 50. |
| `q` | query | string | No | Free-text search term. |
| `sort` | query | string, one of created, name, updated | No | Sort key. |

#### Responses

| Status | Body | Description |
| --- | --- | --- |
| `200` | `application/json`, PagedResultReportDefinitionView | Success. |
| `400` | `application/problem+json`, ProblemDetails | One or more validation errors occurred. |
| `401` | `application/problem+json`, ProblemDetails | No signed-in identity. |
| `403` | `application/problem+json`, ProblemDetails | The identity does not hold report:read. |
| `500` | `application/problem+json`, ProblemDetails | No client store in request context. |

#### Request samples

```bash
# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.
curl -X GET 'https://depot.example.com/api/v1/reports/definitions?dir=asc&page=0&pageSize=0&q=<q>&sort=created' \
  -H 'X-CSRF-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -b 'outpost_console=<console-session>'
```

```powershell
# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.

$headers = @{
    'X-CSRF-Token' = '<csrf-token>'
    'Accept' = 'application/json'
    'Cookie' = 'outpost_console=<console-session>'
}

$response = Invoke-RestMethod `
    -Method Get `
    -Uri 'https://depot.example.com/api/v1/reports/definitions?dir=asc&page=0&pageSize=0&q=<q>&sort=created' `
    -Headers $headers

$response | ConvertTo-Json -Depth 10
```

```python
# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.

import requests

url = "https://depot.example.com/api/v1/reports/definitions"
params = {
    "dir": "asc",
    "page": "0",
    "pageSize": "0",
    "q": "<q>",
    "sort": "created",
}
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}

response = requests.get(url, params=params, headers=headers, cookies=cookies, timeout=30)
response.raise_for_status()
print(response.json())
```

```go
// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.
package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
)

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://depot.example.com/api/v1/reports/definitions?dir=asc&page=0&pageSize=0&q=<q>&sort=created", nil)
	if err != nil {
		log.Fatal(err)
	}

	req.Header.Set("X-CSRF-Token", "<csrf-token>")
	req.Header.Set("Accept", "application/json")
	req.AddCookie(&http.Cookie{Name: "outpost_console", Value: "<console-session>"})

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	out, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(resp.Status, string(out))
}
```

```ts
// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.
// The session cookie is set by signing in. A script cannot set it itself.

const url = new URL("https://depot.example.com/api/v1/reports/definitions");
url.searchParams.set("dir", "asc");
url.searchParams.set("page", "0");
url.searchParams.set("pageSize", "0");
url.searchParams.set("q", "<q>");
url.searchParams.set("sort", "created");

const response = await fetch(url, {
	method: "GET",
	headers: {
		"X-CSRF-Token": "<csrf-token>",
		"Accept": "application/json",
	},
	credentials: "include",
});

if (!response.ok) {
	throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);
```

```csharp
// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.

using System;
using System.Net.Http;

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://depot.example.com/api/v1/reports/definitions?dir=asc&page=0&pageSize=0&q=<q>&sort=created");
request.Headers.TryAddWithoutValidation("X-CSRF-Token", "<csrf-token>");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("Cookie", "outpost_console=<console-session>");

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

### POST `/api/v1/reports/definitions` {#depot.reportdefinitions.createReportDefinition}

**Create report definition**

#### Request body

Required, sent as `application/json`.

#### Responses

| Status | Body | Description |
| --- | --- | --- |
| `201` | `application/json`, ReportDefinitionView | Created. |
| `400` | `application/problem+json`, ProblemDetails | The request body is not valid JSON. |
| `401` | `application/problem+json`, ProblemDetails | No signed-in identity. |
| `403` | `application/problem+json`, ProblemDetails | The identity does not hold report:manage. |
| `404` | `application/problem+json`, ProblemDetails | Report not found. |
| `409` | `application/problem+json`, ProblemDetails | A report with that name already exists. |
| `500` | `application/problem+json`, ProblemDetails | No client store in request context. |

#### Request samples

```bash
# Sign in first. outpost_console is a session cookie, so send it with every request.
curl -X POST 'https://depot.example.com/api/v1/reports/definitions' \
  -H 'X-CSRF-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -b 'outpost_console=<console-session>' \
  --data '{
  "description": "string",
  "name": "string",
  "sections": [
    {
      "columns": [
        "string"
      ],
      "dataset": "string",
      "filters": [
        {
          "column": "string",
          "op": "string",
          "value": "string"
        }
      ],
      "groupBy": "string",
      "limit": 0,
      "sort": [
        {
          "column": "string",
          "desc": false
        }
      ],
      "summary": false,
      "title": "string"
    }
  ]
}'
```

```powershell
# Sign in first. outpost_console is a session cookie, so send it with every request.

$headers = @{
    'X-CSRF-Token' = '<csrf-token>'
    'Accept' = 'application/json'
    'Content-Type' = 'application/json'
    'Cookie' = 'outpost_console=<console-session>'
}

$body = @'
{
  "description": "string",
  "name": "string",
  "sections": [
    {
      "columns": [
        "string"
      ],
      "dataset": "string",
      "filters": [
        {
          "column": "string",
          "op": "string",
          "value": "string"
        }
      ],
      "groupBy": "string",
      "limit": 0,
      "sort": [
        {
          "column": "string",
          "desc": false
        }
      ],
      "summary": false,
      "title": "string"
    }
  ]
}
'@

$response = Invoke-RestMethod `
    -Method Post `
    -Uri 'https://depot.example.com/api/v1/reports/definitions' `
    -Headers $headers `
    -ContentType 'application/json' `
    -Body $body

$response | ConvertTo-Json -Depth 10
```

```python
# Sign in first. outpost_console is a session cookie, so send it with every request.

import requests

url = "https://depot.example.com/api/v1/reports/definitions"
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
    "Content-Type": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}
payload = {
    "description": "string",
    "name": "string",
    "sections": [
        {
            "columns": [
                "string",
            ],
            "dataset": "string",
            "filters": [
                {
                    "column": "string",
                    "op": "string",
                    "value": "string",
                },
            ],
            "groupBy": "string",
            "limit": 0,
            "sort": [
                {
                    "column": "string",
                    "desc": False,
                },
            ],
            "summary": False,
            "title": "string",
        },
    ],
}

response = requests.post(url, headers=headers, cookies=cookies, json=payload, timeout=30)
response.raise_for_status()
print(response.json())
```

```go
// Sign in first. outpost_console is a session cookie, so send it with every request.
package main

import (
	"bytes"
	"fmt"
	"io"
	"log"
	"net/http"
)

func main() {
	body := []byte(`{
  "description": "string",
  "name": "string",
  "sections": [
    {
      "columns": [
        "string"
      ],
      "dataset": "string",
      "filters": [
        {
          "column": "string",
          "op": "string",
          "value": "string"
        }
      ],
      "groupBy": "string",
      "limit": 0,
      "sort": [
        {
          "column": "string",
          "desc": false
        }
      ],
      "summary": false,
      "title": "string"
    }
  ]
}`)

	req, err := http.NewRequest(http.MethodPost, "https://depot.example.com/api/v1/reports/definitions", bytes.NewReader(body))
	if err != nil {
		log.Fatal(err)
	}

	req.Header.Set("X-CSRF-Token", "<csrf-token>")
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")
	req.AddCookie(&http.Cookie{Name: "outpost_console", Value: "<console-session>"})

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	out, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(resp.Status, string(out))
}
```

```ts
// Sign in first. outpost_console is a session cookie, so send it with every request.
// The session cookie is set by signing in. A script cannot set it itself.

const url = "https://depot.example.com/api/v1/reports/definitions";

const response = await fetch(url, {
	method: "POST",
	headers: {
		"X-CSRF-Token": "<csrf-token>",
		"Accept": "application/json",
		"Content-Type": "application/json",
	},
	credentials: "include",
	body: JSON.stringify({
		"description": "string",
		"name": "string",
		"sections": [
			{
				"columns": [
					"string"
				],
				"dataset": "string",
				"filters": [
					{
						"column": "string",
						"op": "string",
						"value": "string"
					}
				],
				"groupBy": "string",
				"limit": 0,
				"sort": [
					{
						"column": "string",
						"desc": false
					}
				],
				"summary": false,
				"title": "string"
			}
		]
	}),
});

if (!response.ok) {
	throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);
```

```csharp
// Sign in first. outpost_console is a session cookie, so send it with every request.

using System;
using System.Net.Http;
using System.Text;

using var client = new HttpClient();

const string body = """
{
  "description": "string",
  "name": "string",
  "sections": [
    {
      "columns": [
        "string"
      ],
      "dataset": "string",
      "filters": [
        {
          "column": "string",
          "op": "string",
          "value": "string"
        }
      ],
      "groupBy": "string",
      "limit": 0,
      "sort": [
        {
          "column": "string",
          "desc": false
        }
      ],
      "summary": false,
      "title": "string"
    }
  ]
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://depot.example.com/api/v1/reports/definitions");
request.Headers.TryAddWithoutValidation("X-CSRF-Token", "<csrf-token>");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("Cookie", "outpost_console=<console-session>");
request.Content = new StringContent(body, Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

### GET `/api/v1/reports/definitions/{definitionId}` {#depot.reportdefinitions.getReportDefinition}

**Get report definition**

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `definitionId` | path | string | Yes | A uuid. |

#### Responses

| Status | Body | Description |
| --- | --- | --- |
| `200` | `application/json`, ReportDefinitionView | Success. |
| `401` | `application/problem+json`, ProblemDetails | No signed-in identity. |
| `403` | `application/problem+json`, ProblemDetails | The identity does not hold report:read. |
| `404` | `application/problem+json`, ProblemDetails | No resource matches that id. |
| `500` | `application/problem+json`, ProblemDetails | No client store in request context. |

#### Request samples

```bash
# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.
curl -X GET 'https://depot.example.com/api/v1/reports/definitions/<definitionId>' \
  -H 'X-CSRF-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -b 'outpost_console=<console-session>'
```

```powershell
# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.

$headers = @{
    'X-CSRF-Token' = '<csrf-token>'
    'Accept' = 'application/json'
    'Cookie' = 'outpost_console=<console-session>'
}

$response = Invoke-RestMethod `
    -Method Get `
    -Uri 'https://depot.example.com/api/v1/reports/definitions/<definitionId>' `
    -Headers $headers

$response | ConvertTo-Json -Depth 10
```

```python
# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.

import requests

url = "https://depot.example.com/api/v1/reports/definitions/<definitionId>"
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}

response = requests.get(url, headers=headers, cookies=cookies, timeout=30)
response.raise_for_status()
print(response.json())
```

```go
// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.
package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
)

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://depot.example.com/api/v1/reports/definitions/<definitionId>", nil)
	if err != nil {
		log.Fatal(err)
	}

	req.Header.Set("X-CSRF-Token", "<csrf-token>")
	req.Header.Set("Accept", "application/json")
	req.AddCookie(&http.Cookie{Name: "outpost_console", Value: "<console-session>"})

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	out, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(resp.Status, string(out))
}
```

```ts
// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.
// The session cookie is set by signing in. A script cannot set it itself.

const url = "https://depot.example.com/api/v1/reports/definitions/<definitionId>";

const response = await fetch(url, {
	method: "GET",
	headers: {
		"X-CSRF-Token": "<csrf-token>",
		"Accept": "application/json",
	},
	credentials: "include",
});

if (!response.ok) {
	throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);
```

```csharp
// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.

using System;
using System.Net.Http;

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://depot.example.com/api/v1/reports/definitions/<definitionId>");
request.Headers.TryAddWithoutValidation("X-CSRF-Token", "<csrf-token>");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("Cookie", "outpost_console=<console-session>");

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

### PUT `/api/v1/reports/definitions/{definitionId}` {#depot.reportdefinitions.updateReportDefinition}

**Update report definition**

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `definitionId` | path | string | Yes | A uuid. |

#### Request body

Required, sent as `application/json`.

#### Responses

| Status | Body | Description |
| --- | --- | --- |
| `200` | `application/json`, ReportDefinitionView | Success. |
| `400` | `application/problem+json`, ProblemDetails | The request body is not valid JSON. |
| `401` | `application/problem+json`, ProblemDetails | No signed-in identity. |
| `403` | `application/problem+json`, ProblemDetails | The identity does not hold report:manage. |
| `404` | `application/problem+json`, ProblemDetails | No resource matches that id. |
| `409` | `application/problem+json`, ProblemDetails | A report with that name already exists. |
| `500` | `application/problem+json`, ProblemDetails | No client store in request context. |

#### Request samples

```bash
# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.
curl -X PUT 'https://depot.example.com/api/v1/reports/definitions/<definitionId>' \
  -H 'X-CSRF-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -b 'outpost_console=<console-session>' \
  --data '{
  "description": "string",
  "name": "string",
  "sections": [
    {
      "columns": [
        "string"
      ],
      "dataset": "string",
      "filters": [
        {
          "column": "string",
          "op": "string",
          "value": "string"
        }
      ],
      "groupBy": "string",
      "limit": 0,
      "sort": [
        {
          "column": "string",
          "desc": false
        }
      ],
      "summary": false,
      "title": "string"
    }
  ]
}'
```

```powershell
# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.

$headers = @{
    'X-CSRF-Token' = '<csrf-token>'
    'Accept' = 'application/json'
    'Content-Type' = 'application/json'
    'Cookie' = 'outpost_console=<console-session>'
}

$body = @'
{
  "description": "string",
  "name": "string",
  "sections": [
    {
      "columns": [
        "string"
      ],
      "dataset": "string",
      "filters": [
        {
          "column": "string",
          "op": "string",
          "value": "string"
        }
      ],
      "groupBy": "string",
      "limit": 0,
      "sort": [
        {
          "column": "string",
          "desc": false
        }
      ],
      "summary": false,
      "title": "string"
    }
  ]
}
'@

$response = Invoke-RestMethod `
    -Method Put `
    -Uri 'https://depot.example.com/api/v1/reports/definitions/<definitionId>' `
    -Headers $headers `
    -ContentType 'application/json' `
    -Body $body

$response | ConvertTo-Json -Depth 10
```

```python
# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.

import requests

url = "https://depot.example.com/api/v1/reports/definitions/<definitionId>"
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
    "Content-Type": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}
payload = {
    "description": "string",
    "name": "string",
    "sections": [
        {
            "columns": [
                "string",
            ],
            "dataset": "string",
            "filters": [
                {
                    "column": "string",
                    "op": "string",
                    "value": "string",
                },
            ],
            "groupBy": "string",
            "limit": 0,
            "sort": [
                {
                    "column": "string",
                    "desc": False,
                },
            ],
            "summary": False,
            "title": "string",
        },
    ],
}

response = requests.put(url, headers=headers, cookies=cookies, json=payload, timeout=30)
response.raise_for_status()
print(response.json())
```

```go
// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.
package main

import (
	"bytes"
	"fmt"
	"io"
	"log"
	"net/http"
)

func main() {
	body := []byte(`{
  "description": "string",
  "name": "string",
  "sections": [
    {
      "columns": [
        "string"
      ],
      "dataset": "string",
      "filters": [
        {
          "column": "string",
          "op": "string",
          "value": "string"
        }
      ],
      "groupBy": "string",
      "limit": 0,
      "sort": [
        {
          "column": "string",
          "desc": false
        }
      ],
      "summary": false,
      "title": "string"
    }
  ]
}`)

	req, err := http.NewRequest(http.MethodPut, "https://depot.example.com/api/v1/reports/definitions/<definitionId>", bytes.NewReader(body))
	if err != nil {
		log.Fatal(err)
	}

	req.Header.Set("X-CSRF-Token", "<csrf-token>")
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")
	req.AddCookie(&http.Cookie{Name: "outpost_console", Value: "<console-session>"})

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	out, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(resp.Status, string(out))
}
```

```ts
// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.
// The session cookie is set by signing in. A script cannot set it itself.

const url = "https://depot.example.com/api/v1/reports/definitions/<definitionId>";

const response = await fetch(url, {
	method: "PUT",
	headers: {
		"X-CSRF-Token": "<csrf-token>",
		"Accept": "application/json",
		"Content-Type": "application/json",
	},
	credentials: "include",
	body: JSON.stringify({
		"description": "string",
		"name": "string",
		"sections": [
			{
				"columns": [
					"string"
				],
				"dataset": "string",
				"filters": [
					{
						"column": "string",
						"op": "string",
						"value": "string"
					}
				],
				"groupBy": "string",
				"limit": 0,
				"sort": [
					{
						"column": "string",
						"desc": false
					}
				],
				"summary": false,
				"title": "string"
			}
		]
	}),
});

if (!response.ok) {
	throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);
```

```csharp
// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.

using System;
using System.Net.Http;
using System.Text;

using var client = new HttpClient();

const string body = """
{
  "description": "string",
  "name": "string",
  "sections": [
    {
      "columns": [
        "string"
      ],
      "dataset": "string",
      "filters": [
        {
          "column": "string",
          "op": "string",
          "value": "string"
        }
      ],
      "groupBy": "string",
      "limit": 0,
      "sort": [
        {
          "column": "string",
          "desc": false
        }
      ],
      "summary": false,
      "title": "string"
    }
  ]
}
""";

var request = new HttpRequestMessage(HttpMethod.Put, "https://depot.example.com/api/v1/reports/definitions/<definitionId>");
request.Headers.TryAddWithoutValidation("X-CSRF-Token", "<csrf-token>");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("Cookie", "outpost_console=<console-session>");
request.Content = new StringContent(body, Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

### DELETE `/api/v1/reports/definitions/{definitionId}` {#depot.reportdefinitions.deleteReportDefinition}

**deleteReportDefinition is a HARD delete and it takes this report's schedules with it, which the store's cascade does rather than this handler.**

A schedule whose definition is gone has nothing to render: leaving it armed is a delivery failure every morning that cannot be turned off from the console, because the page it would be turned off from is the list of definitions.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `definitionId` | path | string | Yes | A uuid. |

#### Responses

| Status | Body | Description |
| --- | --- | --- |
| `204` | None | Success, with no body. |
| `401` | `application/problem+json`, ProblemDetails | No signed-in identity. |
| `403` | `application/problem+json`, ProblemDetails | The identity does not hold report:manage. |
| `404` | `application/problem+json`, ProblemDetails | No resource matches that id. |
| `500` | `application/problem+json`, ProblemDetails | No client store in request context. |

#### Request samples

```bash
# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.
curl -X DELETE 'https://depot.example.com/api/v1/reports/definitions/<definitionId>' \
  -H 'X-CSRF-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -b 'outpost_console=<console-session>'
```

```powershell
# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.

$headers = @{
    'X-CSRF-Token' = '<csrf-token>'
    'Accept' = 'application/json'
    'Cookie' = 'outpost_console=<console-session>'
}

$response = Invoke-RestMethod `
    -Method Delete `
    -Uri 'https://depot.example.com/api/v1/reports/definitions/<definitionId>' `
    -Headers $headers

$response | ConvertTo-Json -Depth 10
```

```python
# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.

import requests

url = "https://depot.example.com/api/v1/reports/definitions/<definitionId>"
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}

response = requests.delete(url, headers=headers, cookies=cookies, timeout=30)
response.raise_for_status()
print(response.json())
```

```go
// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.
package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
)

func main() {
	req, err := http.NewRequest(http.MethodDelete, "https://depot.example.com/api/v1/reports/definitions/<definitionId>", nil)
	if err != nil {
		log.Fatal(err)
	}

	req.Header.Set("X-CSRF-Token", "<csrf-token>")
	req.Header.Set("Accept", "application/json")
	req.AddCookie(&http.Cookie{Name: "outpost_console", Value: "<console-session>"})

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	out, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(resp.Status, string(out))
}
```

```ts
// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.
// The session cookie is set by signing in. A script cannot set it itself.

const url = "https://depot.example.com/api/v1/reports/definitions/<definitionId>";

const response = await fetch(url, {
	method: "DELETE",
	headers: {
		"X-CSRF-Token": "<csrf-token>",
		"Accept": "application/json",
	},
	credentials: "include",
});

if (!response.ok) {
	throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);
```

```csharp
// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.

using System;
using System.Net.Http;

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Delete, "https://depot.example.com/api/v1/reports/definitions/<definitionId>");
request.Headers.TryAddWithoutValidation("X-CSRF-Token", "<csrf-token>");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("Cookie", "outpost_console=<console-session>");

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

### GET `/api/v1/reports/definitions/{definitionId}/run` {#depot.reportdefinitions.runReportDefinition}

**runReportDefinition runs a saved report UNDER THE CALLER'S OWN PERMISSIONS.**

This is the property that makes a saved report safe to share. The definition
is the author's and the permission set is the reader's, so a report written by
somebody who can see vulnerabilities and run by somebody who cannot is a 403
naming vuln:read rather than a document full of CVEs. The engine refuses the
whole run rather than dropping the section, because a report silently missing
a section reads as "there are none".

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `definitionId` | path | string | Yes | A uuid. |
| `format` | query | string | No |  |

#### Responses

| Status | Body | Description |
| --- | --- | --- |
| `200` | `application/octet-stream`, string (binary) | Success. |
| `400` | `application/problem+json`, ProblemDetails | One or more validation errors occurred. |
| `401` | `application/problem+json`, ProblemDetails | Authentication is required. |
| `402` | `application/problem+json`, ProblemDetails | This report is not included in your plan. |
| `403` | `application/problem+json`, ProblemDetails | The identity does not hold the required permission. |
| `404` | `application/problem+json`, ProblemDetails | No resource matches that id. |
| `500` | `application/problem+json`, ProblemDetails | No client store in request context. |

#### Request samples

```bash
# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.
curl -X GET 'https://depot.example.com/api/v1/reports/definitions/<definitionId>/run?format=<format>' \
  -H 'X-CSRF-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -b 'outpost_console=<console-session>'
```

```powershell
# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.

$headers = @{
    'X-CSRF-Token' = '<csrf-token>'
    'Accept' = 'application/json'
    'Cookie' = 'outpost_console=<console-session>'
}

$response = Invoke-RestMethod `
    -Method Get `
    -Uri 'https://depot.example.com/api/v1/reports/definitions/<definitionId>/run?format=<format>' `
    -Headers $headers

$response | ConvertTo-Json -Depth 10
```

```python
# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.

import requests

url = "https://depot.example.com/api/v1/reports/definitions/<definitionId>/run"
params = {
    "format": "<format>",
}
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}

response = requests.get(url, params=params, headers=headers, cookies=cookies, timeout=30)
response.raise_for_status()
print(response.json())
```

```go
// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.
package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
)

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://depot.example.com/api/v1/reports/definitions/<definitionId>/run?format=<format>", nil)
	if err != nil {
		log.Fatal(err)
	}

	req.Header.Set("X-CSRF-Token", "<csrf-token>")
	req.Header.Set("Accept", "application/json")
	req.AddCookie(&http.Cookie{Name: "outpost_console", Value: "<console-session>"})

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	out, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(resp.Status, string(out))
}
```

```ts
// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.
// The session cookie is set by signing in. A script cannot set it itself.

const url = new URL("https://depot.example.com/api/v1/reports/definitions/<definitionId>/run");
url.searchParams.set("format", "<format>");

const response = await fetch(url, {
	method: "GET",
	headers: {
		"X-CSRF-Token": "<csrf-token>",
		"Accept": "application/json",
	},
	credentials: "include",
});

if (!response.ok) {
	throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);
```

```csharp
// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.

using System;
using System.Net.Http;

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://depot.example.com/api/v1/reports/definitions/<definitionId>/run?format=<format>");
request.Headers.TryAddWithoutValidation("X-CSRF-Token", "<csrf-token>");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("Cookie", "outpost_console=<console-session>");

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

### POST `/api/v1/reports/preview` {#depot.reportdefinitions.previewReportDefinition}

**previewReportDefinition runs a definition that has not been saved, so an author sees the table before the report exists.**

Same engine, same permission check, same refusal: a preview that showed more than the saved report will would be worse than no preview.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `format` | query | string | No |  |

#### Request body

Required, sent as `application/json`.

#### Responses

| Status | Body | Description |
| --- | --- | --- |
| `200` | `application/octet-stream`, string (binary) | Success. |
| `400` | `application/problem+json`, ProblemDetails | One or more validation errors occurred. |
| `401` | `application/problem+json`, ProblemDetails | Authentication is required. |
| `402` | `application/problem+json`, ProblemDetails | This report is not included in your plan. |
| `403` | `application/problem+json`, ProblemDetails | The identity does not hold the required permission. |
| `500` | `application/problem+json`, ProblemDetails | No client store in request context. |

#### Request samples

```bash
# Sign in first. outpost_console is a session cookie, so send it with every request.
curl -X POST 'https://depot.example.com/api/v1/reports/preview?format=<format>' \
  -H 'X-CSRF-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -b 'outpost_console=<console-session>' \
  --data '{
  "description": "string",
  "name": "string",
  "sections": [
    {
      "columns": [
        "string"
      ],
      "dataset": "string",
      "filters": [
        {
          "column": "string",
          "op": "string",
          "value": "string"
        }
      ],
      "groupBy": "string",
      "limit": 0,
      "sort": [
        {
          "column": "string",
          "desc": false
        }
      ],
      "summary": false,
      "title": "string"
    }
  ]
}'
```

```powershell
# Sign in first. outpost_console is a session cookie, so send it with every request.

$headers = @{
    'X-CSRF-Token' = '<csrf-token>'
    'Accept' = 'application/json'
    'Content-Type' = 'application/json'
    'Cookie' = 'outpost_console=<console-session>'
}

$body = @'
{
  "description": "string",
  "name": "string",
  "sections": [
    {
      "columns": [
        "string"
      ],
      "dataset": "string",
      "filters": [
        {
          "column": "string",
          "op": "string",
          "value": "string"
        }
      ],
      "groupBy": "string",
      "limit": 0,
      "sort": [
        {
          "column": "string",
          "desc": false
        }
      ],
      "summary": false,
      "title": "string"
    }
  ]
}
'@

$response = Invoke-RestMethod `
    -Method Post `
    -Uri 'https://depot.example.com/api/v1/reports/preview?format=<format>' `
    -Headers $headers `
    -ContentType 'application/json' `
    -Body $body

$response | ConvertTo-Json -Depth 10
```

```python
# Sign in first. outpost_console is a session cookie, so send it with every request.

import requests

url = "https://depot.example.com/api/v1/reports/preview"
params = {
    "format": "<format>",
}
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
    "Content-Type": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}
payload = {
    "description": "string",
    "name": "string",
    "sections": [
        {
            "columns": [
                "string",
            ],
            "dataset": "string",
            "filters": [
                {
                    "column": "string",
                    "op": "string",
                    "value": "string",
                },
            ],
            "groupBy": "string",
            "limit": 0,
            "sort": [
                {
                    "column": "string",
                    "desc": False,
                },
            ],
            "summary": False,
            "title": "string",
        },
    ],
}

response = requests.post(url, params=params, headers=headers, cookies=cookies, json=payload, timeout=30)
response.raise_for_status()
print(response.json())
```

```go
// Sign in first. outpost_console is a session cookie, so send it with every request.
package main

import (
	"bytes"
	"fmt"
	"io"
	"log"
	"net/http"
)

func main() {
	body := []byte(`{
  "description": "string",
  "name": "string",
  "sections": [
    {
      "columns": [
        "string"
      ],
      "dataset": "string",
      "filters": [
        {
          "column": "string",
          "op": "string",
          "value": "string"
        }
      ],
      "groupBy": "string",
      "limit": 0,
      "sort": [
        {
          "column": "string",
          "desc": false
        }
      ],
      "summary": false,
      "title": "string"
    }
  ]
}`)

	req, err := http.NewRequest(http.MethodPost, "https://depot.example.com/api/v1/reports/preview?format=<format>", bytes.NewReader(body))
	if err != nil {
		log.Fatal(err)
	}

	req.Header.Set("X-CSRF-Token", "<csrf-token>")
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")
	req.AddCookie(&http.Cookie{Name: "outpost_console", Value: "<console-session>"})

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	out, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(resp.Status, string(out))
}
```

```ts
// Sign in first. outpost_console is a session cookie, so send it with every request.
// The session cookie is set by signing in. A script cannot set it itself.

const url = new URL("https://depot.example.com/api/v1/reports/preview");
url.searchParams.set("format", "<format>");

const response = await fetch(url, {
	method: "POST",
	headers: {
		"X-CSRF-Token": "<csrf-token>",
		"Accept": "application/json",
		"Content-Type": "application/json",
	},
	credentials: "include",
	body: JSON.stringify({
		"description": "string",
		"name": "string",
		"sections": [
			{
				"columns": [
					"string"
				],
				"dataset": "string",
				"filters": [
					{
						"column": "string",
						"op": "string",
						"value": "string"
					}
				],
				"groupBy": "string",
				"limit": 0,
				"sort": [
					{
						"column": "string",
						"desc": false
					}
				],
				"summary": false,
				"title": "string"
			}
		]
	}),
});

if (!response.ok) {
	throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);
```

```csharp
// Sign in first. outpost_console is a session cookie, so send it with every request.

using System;
using System.Net.Http;
using System.Text;

using var client = new HttpClient();

const string body = """
{
  "description": "string",
  "name": "string",
  "sections": [
    {
      "columns": [
        "string"
      ],
      "dataset": "string",
      "filters": [
        {
          "column": "string",
          "op": "string",
          "value": "string"
        }
      ],
      "groupBy": "string",
      "limit": 0,
      "sort": [
        {
          "column": "string",
          "desc": false
        }
      ],
      "summary": false,
      "title": "string"
    }
  ]
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://depot.example.com/api/v1/reports/preview?format=<format>");
request.Headers.TryAddWithoutValidation("X-CSRF-Token", "<csrf-token>");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("Cookie", "outpost_console=<console-session>");
request.Content = new StringContent(body, Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
```