### Example Project Creation Response

Source: https://github.com/auditumio/auditum/blob/main/website/docs/usage-guide/create-project.md

This is an example of a successful response after creating a project. It includes the project's ID, creation time, and display name.

```json
{
  "project": {
    "id": "01886e86-1963-7f3c-b672-b5d93cec6c6e",
    "create_time": "2023-05-30T21:17:42.115752Z",
    "display_name": "My Project"
  }
}
```

--------------------------------

### Install development tools

Source: https://github.com/auditumio/auditum/blob/main/website/docs/development.md

Installs all required project tools using asdf based on the .tool-versions file.

```shell
asdf install
```

--------------------------------

### Start Jaeger locally

Source: https://github.com/auditumio/auditum/blob/main/website/docs/development.md

Starts a Jaeger instance in Docker with OTLP support enabled for tracing development.

```shell
docker run \
  --name jaeger \
  --rm \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 16686:16686 \
  jaegertracing/all-in-one:1.49
```

--------------------------------

### Start Auditum Service

Source: https://github.com/auditumio/auditum/blob/main/website/docs/getting-started/deployment.md

Launches the Auditum application instance using the specified configuration file.

```shell
auditum serve --config /path/to/config.yaml
```

--------------------------------

### Build Auditum from Source

Source: https://github.com/auditumio/auditum/blob/main/website/docs/getting-started/installation.md

Build the Auditum binary after cloning the repository. This requires Task to be installed.

```shell
task build
```

--------------------------------

### Get Project (HTTP API)

Source: https://context7.com/auditumio/auditum/llms.txt

Retrieve a specific project by its ID using an HTTP GET request. This allows you to fetch the details of a particular project that has already been created.

```bash
curl \
  --request GET \
  --header "Accept: application/json+pretty" \
  "localhost:8080/api/v1alpha1/projects/01886e86-1963-7f3c-b672-b5d93cec6c6e"
```

--------------------------------

### Configure tracing for Jaeger

Source: https://github.com/auditumio/auditum/blob/main/website/docs/development.md

Example configuration snippet to enable OTLP tracing and point to the local Jaeger gRPC endpoint.

```yaml
tracing:
  enabled: true
  exporter: otlp
  otlp:
    endpoint: "grpc://localhost:4317"
```

--------------------------------

### Create Project with gRPC

Source: https://github.com/auditumio/auditum/blob/main/website/docs/features/grpc-api.md

Use this command to create a new project via the gRPC API. Ensure the grpcurl tool is installed and Auditum is running locally on port 9090.

```shell
grpcurl \
  -plaintext \
  -d @ \
  localhost:9090 \
  auditumio.auditum.v1alpha1.ProjectService/CreateProject \
  <<EOM
{
  "project": {
    "display_name": "My Great Project"
  }
}
EOM
```

--------------------------------

### Example JSON Log Output

Source: https://github.com/auditumio/auditum/blob/main/website/docs/features/observability.md

Default structured log format output to standard output.

```json
{"level":"info","time":"2023-06-28T23:08:26.878684Z","logger":"grpc_server_controller","caller":"grpcx/server_controller.go:33","msg":"Starting gRPC server...","addr":":9090"}
```

--------------------------------

### Auditum YAML Configuration

Source: https://context7.com/auditumio/auditum/llms.txt

Example production configuration file for Auditum, including logging, tracing, and storage settings.

```yaml
log:
  format: json  # json or text
  level: info   # debug, info, warn, error

tracing:
  enabled: true
  exporter: otlp  # log, jaeger, or otlp
  otlp:
    endpoint: "http://otel-collector:4318"

http:
  port: 8080

grpc:
  port: 9090

store:
  type: postgres  # sqlite or postgres
  postgres:
    host: "postgres.example.com"
    port: 5432
    database: auditum_db
    username: auditum_user
    password: "${POSTGRES_PASSWORD}"
    sslmode: require
    logQueries: false

settings:
  records:
    updateEnabled: false  # Keep records immutable
    deleteEnabled: true   # Allow deletion for GDPR compliance
    restrictions:
      labels:
        keyMaxSizeBytes: 64
        valueMaxSizeBytes: 256
        totalMaxSizeBytes: 2048
      resource:
        changes:
          totalMaxCount: 20
```

--------------------------------

### Clone Auditum Repository

Source: https://github.com/auditumio/auditum/blob/main/website/docs/getting-started/installation.md

Clone the Auditum repository to build from source. Ensure you have Go and Task installed.

```shell
git clone https://github.com/auditumio/auditum.git
cd auditum
```

--------------------------------

### Run PostgreSQL Database Migrations

Source: https://github.com/auditumio/auditum/blob/main/website/docs/getting-started/deployment.md

Executes schema migrations for the PostgreSQL database. This must be performed before starting the application and after every version upgrade.

```shell
auditum migrate --config /path/to/config.yaml
```

--------------------------------

### GET /api/v1alpha1/projects/{id}

Source: https://context7.com/auditumio/auditum/llms.txt

Retrieves a specific project by its unique ID.

```APIDOC
## GET /api/v1alpha1/projects/{id}

### Description
Retrieve a specific project by its ID.

### Method
GET

### Endpoint
/api/v1alpha1/projects/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique ID of the project

### Response
#### Success Response (200)
- **project** (object) - The project details

#### Response Example
{
  "project": {
    "id": "01886e86-1963-7f3c-b672-b5d93cec6c6e",
    "create_time": "2023-05-30T21:17:42.115752Z",
    "display_name": "My E-Commerce App"
  }
}
```

--------------------------------

### GET /api/v1alpha1/projects

Source: https://context7.com/auditumio/auditum/llms.txt

Retrieves a paginated list of all projects, with optional filtering by external IDs.

```APIDOC
## GET /api/v1alpha1/projects

### Description
Retrieve a paginated list of all projects, optionally filtering by external IDs.

### Method
GET

### Endpoint
/api/v1alpha1/projects

### Parameters
#### Query Parameters
- **page_size** (integer) - Optional - Number of items per page
- **filter.external_ids** (array) - Optional - List of external IDs to filter by

### Response
#### Success Response (200)
- **projects** (array) - List of project objects
- **next_page_token** (string) - Token for the next page of results

#### Response Example
{
  "projects": [
    {
      "id": "01886e86-1963-7f3c-b672-b5d93cec6c6e",
      "create_time": "2023-05-30T21:17:42.115752Z",
      "display_name": "My E-Commerce App",
      "external_id": "tenant-123"
    }
  ],
  "next_page_token": ""
}
```

--------------------------------

### Query Records Response

Source: https://github.com/auditumio/auditum/blob/main/website/docs/quickstart.md

Example JSON response containing a list of audit records.

```json
{
  "records": [
    {
      "id": "01886e87-8f8f-7f3c-b987-2680f63120b8",
      "project_id": "01886e86-1963-7f3c-b672-b5d93cec6c6e",
      "create_time": "2023-05-30T21:19:17.903783Z",
      "labels": {
        "post_id": "post-42"
      },
      "resource": {
        "type": "POST",
        "id": "post-42",
        "metadata": {
          "category": "funny"
        },
        "changes": [
          {
            "name": "text",
            "old_value": null,
            "new_value": "My windows aren’t dirty, that’s my dog’s nose art."
          },
          {
            "name": "status",
            "old_value": null,
            "new_value": "published"
          }
        ]
      },
      "operation": {
        "type": "CREATE",
        "id": "example.v1.PostService/CreatePost",
        "time": "2023-01-02T03:01:00Z",
        "trace_context": {
          "traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
          "tracestate": "congo=t61rcWkgMzE"
        },
        "status": "SUCCEEDED"
      },
      "actor": {
        "type": "USER",
        "id": "user-82"
      }
    }
  ],
  "next_page_token": ""
}
```

--------------------------------

### Search Records

Source: https://github.com/auditumio/auditum/blob/main/website/docs/usage-guide/search-records.md

Send a GET request to the /projects/{project_id}/records endpoint to search for records. You can specify the page size using the `page_size` query parameter.

```APIDOC
## GET /projects/{project_id}/records

### Description
Retrieves a paginated list of records for a given project.

### Method
GET

### Endpoint
/projects/{project_id}/records

#### Query Parameters
- **page_size** (integer) - Optional - The number of records to return per page.

### Request Example
```shell
curl \
  --request GET \
  --header "Accept: application/json+pretty" \
  --get \
  --data "page_size=2" \
  "localhost:8080/api/v1alpha1/projects/01886e86-1963-7f3c-b672-b5d93cec6c6e/records"
```

### Response
#### Success Response (200)
- **records** (array) - A list of record objects.
- **next_page_token** (string) - A token to retrieve the next page of results.

#### Response Example
```json
{
  "records": [
    {
      "id": "01886e90-69aa-7f3e-97c4-cdef2436ad20",
      "project_id": "01886e86-1963-7f3c-b672-b5d93cec6c6e",
      "create_time": "2023-05-30T21:28:58.026109Z",
      "labels": {
        "post_id": "post-55"
      },
      "resource": {
        "type": "POST",
        "id": "post-55",
        "metadata": {
          "status": "draft"
        },
        "changes": [
          {
            "name": "text",
            "description": "Edit text",
            "old_value": "The dog knows the best seat in the house.",
            "new_value": "For the best seat in the house, you’ll have to move the dog."
          }
        ]
      },
      "operation": {
        "type": "UPDATE",
        "id": "example.v1.PostService/Post",
        "time": "2023-01-02T03:04:00Z",
        "status": "SUCCEEDED"
      },
      "actor": {
        "type": "USER",
        "id": "user-83"
      }
    },
    {
      "id": "01886e90-69aa-7f3d-b8a1-df1742963d96",
      "project_id": "01886e86-1963-7f3c-b672-b5d93cec6c6e",
      "create_time": "2023-05-30T21:28:58.026109Z",
      "labels": {
        "post_id": "post-42"
      },
      "resource": {
        "type": "COMMENT",
        "id": "comment-79",
        "metadata": {
          "status": "published"
        },
        "changes": [
          {
            "name": "text",
            "description": "Edit text",
            "old_value": "Show us, my fiend!",
            "new_value": "Show us, my friend!"
          }
        ]
      },
      "operation": {
        "type": "UPDATE",
        "id": "example.v1.PostService/UpdatePostComment",
        "time": "2023-01-02T03:03:00Z",
        "status": "SUCCEEDED"
      },
      "actor": {
        "type": "USER",
        "id": "user-83"
      }
    }
  ],
  "next_page_token": "eyJsb3QiOiIyMDIzLTAxLTAyVDAzOjAzOjAwWiIsImxpZCI6WzEsMTM2LDExMCwxNDQsMTA1LDE3MCwxMjcsNjEsMTg0LDE2MSwyMjMsMjMsNjYsMTUwLDYxLDE1MF19"
}
```
```

--------------------------------

### Run Auditum with Docker

Source: https://context7.com/auditumio/auditum/llms.txt

Start Auditum as a Docker container for quick testing and development. The server exposes HTTP API on port 8080 and gRPC API on port 9090. Choose between default in-memory SQLite, PostgreSQL backend, or custom configuration.

```bash
# Start Auditum with default in-memory SQLite database
docker run -p 8080:8080 -p 9090:9090 auditumio/auditum:latest
```

```bash
# Start with PostgreSQL backend
docker run \
  -p 8080:8080 \
  -p 9090:9090 \
  -e AUDITUM_store_type=postgres \
  -e AUDITUM_store_postgres_host=host.docker.internal \
  -e AUDITUM_store_postgres_username=auditum \
  -e AUDITUM_store_postgres_password=secret \
  auditumio/auditum:latest
```

```bash
# Start with custom configuration file
docker run \
  -p 8080:8080 \
  -p 9090:9090 \
  -v /path/to/config.yaml:/config.yaml \
  auditumio/auditum:latest \
  --config /config.yaml
```

--------------------------------

### Filter Audit Records by Labels (HTTP API)

Source: https://context7.com/auditumio/auditum/llms.txt

Query audit records using label-based filtering. This example shows how to retrieve all records associated with a specific order ID.

```bash
# Filter by labels (e.g., get all records for a specific order)
curl \
  --request GET \
  --header "Accept: application/json+pretty" \
  --get \
  --data-urlencode "filter.labels[order_id]=order-1001" \
  "localhost:8080/api/v1alpha1/projects/01886e86-1963-7f3c-b672-b5d93cec6c6e/records"

```

--------------------------------

### Example Response for Record Update

Source: https://github.com/auditumio/auditum/blob/main/website/docs/usage-guide/update-records.md

This JSON object represents a successful response after updating an audit log record. It includes the updated record details, resource information, and the operation performed.

```json
{
  "record": {
    "id": "01886e90-69aa-7f3e-97c4-cdef2436ad20",
    "project_id": "01886e86-1963-7f3c-b672-b5d93cec6c6e",
    "create_time": "2023-05-30T21:28:58.026109Z",
    "labels": {
      "post_id": "post-55",
      "category": "funny"
    },
    "resource": {
      "type": "POST",
      "id": "post-55",
      "metadata": {
        "status": "draft"
      },
      "changes": [
        {
          "name": "text",
          "description": "Edit text",
          "old_value": "The dog knows the best seat in the house.",
          "new_value": "For the best seat in the house, you’ll have to move the dog."
        }
      ]
    },
    "operation": {
      "type": "UPDATE",
      "id": "example.v1.PostService/Post",
      "time": "2023-01-02T03:04:00Z",
      "status": "SUCCEEDED"
    },
    "actor": {
      "type": "USER",
      "id": "user-83"
    }
  }
}
```

--------------------------------

### Create Project via gRPC

Source: https://context7.com/auditumio/auditum/llms.txt

Initialize a new project using the gRPC service definition.

```bash
grpcurl \
  -plaintext \
  -d @ \
  localhost:9090 \
  auditumio.auditum.v1alpha1.ProjectService/CreateProject \
  <<EOM
{
  "project": {
    "display_name": "My gRPC Project"
  }
}
EOM
```

--------------------------------

### List Projects via gRPC

Source: https://context7.com/auditumio/auditum/llms.txt

Retrieve a list of all projects configured in the system.

```bash
grpcurl \
  -plaintext \
  -d '{}' \
  localhost:9090 \
  auditumio.auditum.v1alpha1.ProjectService/ListProjects
```

--------------------------------

### GET /api/v1alpha1/projects/{project_id}/records/{record_id}

Source: https://context7.com/auditumio/auditum/llms.txt

Retrieve a specific audit record by its ID.

```APIDOC
## GET /api/v1alpha1/projects/{project_id}/records/{record_id}

### Description
Retrieve a specific audit record by its ID.

### Method
GET

### Endpoint
/api/v1alpha1/projects/{project_id}/records/{record_id}

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.
- **record_id** (string) - Required - The ID of the record to retrieve.

### Response
#### Success Response (200)
- **record** (object) - The audit record details.
  - **id** (string) - The unique identifier of the record.
  - **project_id** (string) - The ID of the project the record belongs to.
  - **create_time** (string) - The timestamp when the record was created.
  - **labels** (object) - Key-value pairs for labeling the record.
  - **resource** (object) - Information about the resource associated with the record.
  - **operation** (object) - Details about the operation that generated the record.
  - **actor** (object) - Information about the actor who performed the operation.

### Response Example
```json
{
  "record": {
    "id": "01886e87-8f8f-7f3c-b987-2680f63120b8",
    "project_id": "01886e86-1963-7f3c-b672-b5d93cec6c6e",
    "create_time": "2023-06-15T14:30:05.123456Z",
    "labels": { "order_id": "order-1001" },
    "resource": { ... },
    "operation": { ... },
    "actor": { ... }
  }
}
```
```

--------------------------------

### List Projects with gRPC

Source: https://github.com/auditumio/auditum/blob/main/website/docs/features/grpc-api.md

Use this command to list all existing projects via the gRPC API. This is useful for verifying project creation or retrieving project details.

```shell
grpcurl \
  -plaintext \
  -d @ \
  localhost:9090 \
  auditumio.auditum.v1alpha1.ProjectService/ListProjects \
  <<EOM
{}
EOM
```

--------------------------------

### Get Audit Record via HTTP

Source: https://context7.com/auditumio/auditum/llms.txt

Retrieve a specific audit record by its unique identifier.

```bash
curl \
  --request GET \
  --header "Accept: application/json+pretty" \
  "localhost:8080/api/v1alpha1/projects/01886e86-1963-7f3c-b672-b5d93cec6c6e/records/01886e87-8f8f-7f3c-b987-2680f63120b8"
```

--------------------------------

### GET /api/v1alpha1/projects/{project_id}/records

Source: https://context7.com/auditumio/auditum/llms.txt

Queries and lists audit records with support for filtering and pagination.

```APIDOC
## GET /api/v1alpha1/projects/{project_id}/records

### Description
Query audit records with filtering by resource, operation, actor, labels, and time range. Results are paginated and sorted by operation time.

### Method
GET

### Endpoint
/api/v1alpha1/projects/{project_id}/records

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The unique identifier of the project.

#### Query Parameters
- **page_size** (integer) - Optional - Number of records to return.
- **filter.resource_type** (string) - Optional - Filter by resource type.
- **filter.resource_id** (string) - Optional - Filter by resource ID.
- **filter.actor_type** (string) - Optional - Filter by actor type.
- **filter.actor_id** (string) - Optional - Filter by actor ID.
- **filter.operation_type** (string) - Optional - Filter by operation type.
- **filter.operation_time_from** (string) - Optional - Start time range.
- **filter.operation_time_to** (string) - Optional - End time range.
- **filter.labels[key]** (string) - Optional - Filter by specific label key-value pairs.
```

--------------------------------

### POST /projects

Source: https://github.com/auditumio/auditum/blob/main/website/docs/usage-guide/create-project.md

Creates a new project with a specified display name.

```APIDOC
## POST /projects

### Description
Creates a new project.

### Method
POST

### Endpoint
/projects

### Request Body
- **project** (object) - Required - Contains project details.
  - **display_name** (string) - Required - The desired display name for the project.

### Request Example
```json
{
  "project": {
    "display_name": "My Project"
  }
}
```

### Response
#### Success Response (200)
- **project** (object) - Details of the created project.
  - **id** (string) - The unique identifier for the project.
  - **create_time** (string) - The timestamp when the project was created.
  - **display_name** (string) - The display name of the project.

#### Response Example
```json
{
  "project": {
    "id": "01886e86-1963-7f3c-b672-b5d93cec6c6e",
    "create_time": "2023-05-30T21:17:42.115752Z",
    "display_name": "My Project"
  }
}
```
```

--------------------------------

### Create Project Request

Source: https://github.com/auditumio/auditum/blob/main/website/docs/usage-guide/create-project.md

Use this cURL command to create a new project. Ensure the Content-Type and Accept headers are set correctly. The request body should contain the project's display name.

```shell
curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json+pretty" \
  --data @- \
  "localhost:8080/api/v1alpha1/projects" \
  <<EOM
{
  "project": {
    "display_name": "My Project"
  }
}
EOM
```

--------------------------------

### Configure Auditum via Environment Variables

Source: https://context7.com/auditumio/auditum/llms.txt

Set these environment variables to configure database connections, server ports, logging, tracing, and record settings.

```bash
export AUDITUM_store_type=postgres
export AUDITUM_store_postgres_host=localhost
export AUDITUM_store_postgres_port=5432
export AUDITUM_store_postgres_database=auditum_db
export AUDITUM_store_postgres_username=auditum
export AUDITUM_store_postgres_password=secret
export AUDITUM_store_postgres_sslmode=disable

# Server configuration
export AUDITUM_http_port=8080
export AUDITUM_grpc_port=9090

# Logging
export AUDITUM_log_format=json
export AUDITUM_log_level=info

# Tracing
export AUDITUM_tracing_enabled=true
export AUDITUM_tracing_exporter=otlp
export AUDITUM_tracing_otlp_endpoint=http://localhost:4318

# Record settings
export AUDITUM_settings_records_updateEnabled=false
export AUDITUM_settings_records_deleteEnabled=false

# Start Auditum
auditum --config /path/to/config.yaml
```

--------------------------------

### Create Project (HTTP API)

Source: https://context7.com/auditumio/auditum/llms.txt

Use this `curl` command to create a new project in Auditum. Projects are used to logically group audit records and typically correspond to individual applications being audited. Ensure the `Content-Type` and `Accept` headers are set correctly.

```bash
curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json+pretty" \
  --data @- \
  "localhost:8080/api/v1alpha1/projects" \
  <<EOM
{
  "project": {
    "display_name": "My E-Commerce App",
    "external_id": "tenant-123"
  }
}
EOM
```

--------------------------------

### gRPC API - ProjectService/ListProjects

Source: https://context7.com/auditumio/auditum/llms.txt

List all projects using gRPC.

```APIDOC
## gRPC API - ProjectService/ListProjects

### Description
List all projects using gRPC.

### Method
RPC

### Endpoint
auditumio.auditum.v1alpha1.ProjectService/ListProjects

### Response
#### Success Response (200)
- **projects** (array) - A list of projects.
  - **id** (string) - The unique identifier of the project.
  - **createTime** (string) - The timestamp when the project was created.
  - **displayName** (string) - The display name of the project.

### Response Example
```json
{
  "projects": [
    {
      "id": "01886e86-1963-7f3c-b672-b5d93cec6c6e",
      "createTime": "2023-05-30T21:17:42.115752Z",
      "displayName": "My gRPC Project"
    }
  ]
}
```
```

--------------------------------

### gRPC API - ProjectService/CreateProject

Source: https://context7.com/auditumio/auditum/llms.txt

Use the gRPC API for better performance and type safety. Protobuf definitions are available for code generation in any language.

```APIDOC
## gRPC API - ProjectService/CreateProject

### Description
Use the gRPC API for better performance and type safety. Protobuf definitions are available for code generation in any language.

### Method
RPC

### Endpoint
auditumio.auditum.v1alpha1.ProjectService/CreateProject

### Request Body
- **project** (object) - Required - The project details to create.
  - **display_name** (string) - Required - The display name for the project.

### Request Example
```json
{
  "project": {
    "display_name": "My gRPC Project"
  }
}
```

### Response
#### Success Response (200)
- **project** (object) - The created project details.
  - **id** (string) - The unique identifier of the project.
  - **createTime** (string) - The timestamp when the project was created.
  - **displayName** (string) - The display name of the project.

### Response Example
```json
{
  "project": {
    "id": "01886e86-1963-7f3c-b672-b5d93cec6c6e",
    "createTime": "2023-05-30T21:17:42.115752Z",
    "displayName": "My gRPC Project"
  }
}
```
```

--------------------------------

### Search Records Request and Response

Source: https://github.com/auditumio/auditum/blob/main/website/docs/usage-guide/search-records.md

Use this request to fetch a paginated list of records for a specific project. The response includes record details, resource changes, and a pagination token.

```shell
curl \
  --request GET \
  --header "Accept: application/json+pretty" \
  --get \
  --data "page_size=2" \
  "localhost:8080/api/v1alpha1/projects/01886e86-1963-7f3c-b672-b5d93cec6c6e/records"
```

```json
{
  "records": [
    {
      "id": "01886e90-69aa-7f3e-97c4-cdef2436ad20",
      "project_id": "01886e86-1963-7f3c-b672-b5d93cec6c6e",
      "create_time": "2023-05-30T21:28:58.026109Z",
      "labels": {
        "post_id": "post-55"
      },
      "resource": {
        "type": "POST",
        "id": "post-55",
        "metadata": {
          "status": "draft"
        },
        "changes": [
          {
            "name": "text",
            "description": "Edit text",
            "old_value": "The dog knows the best seat in the house.",
            "new_value": "For the best seat in the house, you’ll have to move the dog."
          }
        ]
      },
      "operation": {
        "type": "UPDATE",
        "id": "example.v1.PostService/Post",
        "time": "2023-01-02T03:04:00Z",
        "status": "SUCCEEDED"
      },
      "actor": {
        "type": "USER",
        "id": "user-83"
      }
    },
    {
      "id": "01886e90-69aa-7f3d-b8a1-df1742963d96",
      "project_id": "01886e86-1963-7f3c-b672-b5d93cec6c6e",
      "create_time": "2023-05-30T21:28:58.026109Z",
      "labels": {
        "post_id": "post-42"
      },
      "resource": {
        "type": "COMMENT",
        "id": "comment-79",
        "metadata": {
          "status": "published"
        },
        "changes": [
          {
            "name": "text",
            "description": "Edit text",
            "old_value": "Show us, my fiend!",
            "new_value": "Show us, my friend!"
          }
        ]
      },
      "operation": {
        "type": "UPDATE",
        "id": "example.v1.PostService/UpdatePostComment",
        "time": "2023-01-02T03:03:00Z",
        "status": "SUCCEEDED"
      },
      "actor": {
        "type": "USER",
        "id": "user-83"
      }
    }
  ],
  "next_page_token": "eyJsb3QiOiIyMDIzLTAxLTAyVDAzOjAzOjAwWiIsImxpZCI6WzEsMTM2LDExMCwxNDQsMTA1LDE3MCwxMjcsNjEsMTg0LDE2MSwyMjMsMjMsNjYsMTUwLDYxLDE1MF19"
}
```

--------------------------------

### Configure Jaeger Tracing

Source: https://github.com/auditumio/auditum/blob/main/website/docs/features/observability.md

Configuration snippet to enable and set up the Jaeger tracing exporter.

```yaml
tracing:
  enabled: true
  exporter: jaeger
  jaeger:
    endpoint: http://localhost:14268/api/traces
```

--------------------------------

### List Projects (HTTP API)

Source: https://context7.com/auditumio/auditum/llms.txt

Retrieve a paginated list of all projects using the HTTP API. You can optionally filter by external IDs, which is useful for multi-tenancy scenarios. The `page_size` parameter controls the number of results per page.

```bash
# List all projects with pagination
curl \
  --request GET \
  --header "Accept: application/json+pretty" \
  "localhost:8080/api/v1alpha1/projects?page_size=10"
```

```bash
# Filter by external IDs (useful for multi-tenancy)
curl \
  --request GET \
  --header "Accept: application/json+pretty" \
  "localhost:8080/api/v1alpha1/projects?filter.external_ids=tenant-123&filter.external_ids=tenant-456"
```

--------------------------------

### Create Audit Record via gRPC

Source: https://context7.com/auditumio/auditum/llms.txt

Submit a new audit record using the gRPC RecordService.

```bash
grpcurl \
  -plaintext \
  -d @ \
  localhost:9090 \
  auditumio.auditum.v1alpha1.RecordService/CreateRecord \
  <<EOM
{
  "project_id": "01886e86-1963-7f3c-b672-b5d93cec6c6e",
  "record": {
    "resource": {
      "type": "DOCUMENT",
      "id": "doc-555"
    },
    "operation": {
      "type": "CREATE",
      "id": "docs.v1.DocumentService/CreateDocument",
      "time": "2023-06-20T09:00:00Z",
      "status": "SUCCEEDED"
    },
    "actor": {
      "type": "SERVICE_ACCOUNT",
      "id": "doc-generator"
    }
  }
}
EOM
```

--------------------------------

### Create an Audit Record

Source: https://github.com/auditumio/auditum/blob/main/website/docs/quickstart.md

Sends a new audit record to the specified project.

```shell
curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json+pretty" \
  --data @- \
  "localhost:8080/api/v1alpha1/projects/01886e86-1963-7f3c-b672-b5d93cec6c6e/records" \
  <<EOM
{
  "record": {
    "labels": {
      "post_id": "post-42"
    },
    "resource": {
      "type": "POST",
      "id": "post-42",
      "metadata": {
        "category": "funny"
      },
      "changes": [
        {
          "name": "text",
          "old_value": null,
          "new_value": "My windows aren’t dirty, that’s my dog’s nose art."
        },
        {
          "name": "status",
          "old_value": null,
          "new_value": "published"
        }
      ]
    },
    "operation": {
      "type": "CREATE",
      "id": "example.v1.PostService/CreatePost",
      "time": "2023-01-02T03:01:00Z",
      "trace_context": {
        "traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
        "tracestate": "congo=t61rcWkgMzE"
      },
      "status": "SUCCEEDED"
    },
    "actor": {
      "type": "USER",
      "id": "user-82"
    }
  }
}
EOM
```

--------------------------------

### POST /projects/{project_id}/records:batchCreate

Source: https://github.com/auditumio/auditum/blob/main/website/docs/usage-guide/create-records.md

Creates a batch of records for a specified project.

```APIDOC
## POST /projects/{project_id}/records:batchCreate

### Description
Creates a batch of records for a specified project.

### Method
POST

### Endpoint
/api/v1alpha1/projects/{project_id}/records:batchCreate

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The unique identifier of the project.

### Request Example
{
  "records": [
    {
      "labels": {
        "post_id": "post-42"
      },
      "resource": {
        "type": "COMMENT",
        "id": "comment-79",
        "changes": [
          {
            "name": "title",
            "old_value": null,
            "new_value": "Show us, my fiend!"
          }
        ]
      },
      "operation": {
        "type": "CREATE",
        "id": "example.v1.PostService/CreatePostComment",
        "time": "2023-01-02T03:02:00Z",
        "status": "SUCCEEDED"
      },
      "actor": {
        "type": "USER",
        "id": "user-83"
      }
    }
  ]
}

### Response
#### Success Response (200)
- **records** (array) - A list of created record objects.

#### Response Example
{
  "records": [
    {
      "id": "01886e90-69aa-7f3c-8be4-ecc65845e380",
      "project_id": "01886e86-1963-7f3c-b672-b5d93cec6c6e",
      "create_time": "2023-05-30T21:28:58.026109Z"
    }
  ]
}
```

--------------------------------

### Link OpenAPI v1alpha1 API

Source: https://github.com/auditumio/auditum/blob/main/website/redocusaurus/openapi/README.md

Create a symbolic link for the OpenAPI v1alpha1 API definition. This command should be run from the repository root.

```shell
ln -s ../../../../api/gen/openapiv2/auditumio/auditum/v1alpha1/api.swagger.yaml website/redocusaurus/openapi/v1alpha1/api.yaml
```

--------------------------------

### Run Auditum with Docker

Source: https://github.com/auditumio/auditum/blob/main/website/docs/getting-started/installation.md

Use this command to run the latest Auditum Docker image, exposing port 8080.

```shell
docker run \
  -p 8080:8080 \
  auditumio/auditum:latest
```

--------------------------------

### Set Auditum Log Format via Environment Variable

Source: https://github.com/auditumio/auditum/blob/main/website/docs/getting-started/configuration.md

Configure Auditum settings using environment variables. Variables are prefixed with AUDITUM_ and use underscore-separated keys corresponding to configuration options, such as setting 'log.format' to 'text'.

```shell
export AUDITUM_log_format=text
```

--------------------------------

### Create Batch Records Request

Source: https://github.com/auditumio/auditum/blob/main/website/docs/usage-guide/create-records.md

Send a POST request to the /projects/{project_id}/records:batchCreate endpoint with a JSON payload containing the records to be created. Ensure the Content-Type and Accept headers are set correctly.

```shell
curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json+pretty" \
  --data @- \
  "localhost:8080/api/v1alpha1/projects/01886e86-1963-7f3c-b672-b5d93cec6c6e/records:batchCreate" \
  <<EOM
{
  "records": [
    {
      "labels": {
        "post_id": "post-42"
      },
      "resource": {
        "type": "COMMENT",
        "id": "comment-79",
        "changes": [
          {
            "name": "title",
            "old_value": null,
            "new_value": "Show us, my fiend!"
          },
          {
            "name": "status",
            "old_value": null,
            "new_value": "published"
          }
        ]
      },
      "operation": {
        "type": "CREATE",
        "id": "example.v1.PostService/CreatePostComment",
        "time": "2023-01-02T03:02:00Z",
        "status": "SUCCEEDED"
      },
      "actor": {
        "type": "USER",
        "id": "user-83"
      }
    },
    {
      "labels": {
        "post_id": "post-42"
      },
      "resource": {
        "type": "COMMENT",
        "id": "comment-79",
        "metadata": {
          "status": "published"
        },
        "changes": [
          {
            "name": "text",
            "description": "Edit text",
            "old_value": "Show us, my fiend!",
            "new_value": "Show us, my friend!"
          }
        ]
      },
      "operation": {
        "type": "UPDATE",
        "id": "example.v1.PostService/UpdatePostComment",
        "time": "2023-01-02T03:03:00Z",
        "status": "SUCCEEDED"
      },
      "actor": {
        "type": "USER",
        "id": "user-83"
      }
    },
    {
      "labels": {
        "post_id": "post-55"
      },
      "resource": {
        "type": "POST",
        "id": "post-55",
        "metadata": {
          "status": "draft"
        },
        "changes": [
          {
            "name": "text",
            "description": "Edit text",
            "old_value": "The dog knows the best seat in the house.",
            "new_value": "For the best seat in the house, you’ll have to move the dog."
          }
        ]
      },
      "operation": {
        "type": "UPDATE",
        "id": "example.v1.PostService/Post",
        "time": "2023-01-02T03:04:00Z",
        "status": "SUCCEEDED"
      },
      "actor": {
        "type": "USER",
        "id": "user-83"
      }
    }
  ]
}
EOM
```

--------------------------------

### POST /api/v1alpha1/projects

Source: https://context7.com/auditumio/auditum/llms.txt

Creates a new project to logically group audit records.

```APIDOC
## POST /api/v1alpha1/projects

### Description
Creates a new project to logically group audit records. Projects typically correspond to individual applications being audited.

### Method
POST

### Endpoint
/api/v1alpha1/projects

### Request Body
- **project** (object) - Required - The project details
  - **display_name** (string) - Required - The display name of the project
  - **external_id** (string) - Optional - An external identifier for the project

### Response
#### Success Response (200)
- **project** (object) - The created project object
  - **id** (string) - Unique project ID
  - **create_time** (string) - Timestamp of creation
  - **display_name** (string) - Display name
  - **external_id** (string) - External ID

#### Response Example
{
  "project": {
    "id": "01886e86-1963-7f3c-b672-b5d93cec6c6e",
    "create_time": "2023-05-30T21:17:42.115752Z",
    "display_name": "My E-Commerce App",
    "external_id": "tenant-123"
  }
}
```

--------------------------------

### List Audit Records with Pagination (HTTP API)

Source: https://context7.com/auditumio/auditum/llms.txt

Retrieve a paginated list of audit records. Specify the desired page size using the `page_size` query parameter. Results are sorted by operation time, newest first.

```bash
# List all records with pagination
curl \
  --request GET \
  --header "Accept: application/json+pretty" \
  "localhost:8080/api/v1alpha1/projects/01886e86-1963-7f3c-b672-b5d93cec6c6e/records?page_size=20"

```

--------------------------------

### Create Batch Audit Records (HTTP API)

Source: https://context7.com/auditumio/auditum/llms.txt

Use this endpoint for efficient bulk ingestion of up to 100 audit records per request. Set the Content-Type and Accept headers, and provide a JSON array of records in the request body.

```bash
curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json+pretty" \
  --data @- \
  "localhost:8080/api/v1alpha1/projects/01886e86-1963-7f3c-b672-b5d93cec6c6e/records:batchCreate" \
  <<EOM
{
  "records": [
    {
      "labels": { "session_id": "sess-abc123" },
      "resource": {
        "type": "USER_SESSION",
        "id": "sess-abc123"
      },
      "operation": {
        "type": "CREATE",
        "id": "auth.v1.SessionService/CreateSession",
        "time": "2023-06-15T10:00:00Z",
        "status": "SUCCEEDED"
      },
      "actor": {
        "type": "USER",
        "id": "user-100"
      }
    },
    {
      "labels": { "session_id": "sess-abc123" },
      "resource": {
        "type": "USER_SESSION",
        "id": "sess-abc123",
        "changes": [
          {
            "name": "last_activity",
            "old_value": "2023-06-15T10:00:00Z",
            "new_value": "2023-06-15T10:30:00Z"
          }
        ]
      },
      "operation": {
        "type": "UPDATE",
        "id": "auth.v1.SessionService/RefreshSession",
        "time": "2023-06-15T10:30:00Z",
        "status": "SUCCEEDED"
      },
      "actor": {
        "type": "SYSTEM",
        "id": "session-manager"
      }
    }
  ]
}
EOM

```

--------------------------------

### Run Specific Auditum Docker Version

Source: https://github.com/auditumio/auditum/blob/main/website/docs/getting-started/installation.md

Run a specific version of Auditum from the GitHub Container Registry, exposing port 8080.

```shell
docker run \
  -p 8080:8080 \
  ghcr.io/auditumio/auditum:0.1.0
```

--------------------------------

### Configure OpenTelemetry Tracing

Source: https://context7.com/auditumio/auditum/llms.txt

Define tracing exporters in the configuration file to send data to OTLP collectors, Jaeger, or stdout.

```yaml
# Export to OpenTelemetry Collector (recommended)
tracing:
  enabled: true
  exporter: otlp
  otlp:
    endpoint: "http://otel-collector:4318"  # HTTP
    # endpoint: "grpc://otel-collector:4317"  # gRPC

# Export to Jaeger directly (deprecated, use OTLP)
tracing:
  enabled: true
  exporter: jaeger
  jaeger:
    endpoint: "http://jaeger:14268/api/traces"

# Export to stdout for debugging
tracing:
  enabled: true
  exporter: log
  log:
    pretty: true
```

--------------------------------

### POST /api/v1alpha1/projects/{project_id}/records:batchCreate

Source: https://context7.com/auditumio/auditum/llms.txt

Creates multiple audit records in a single request for efficient bulk ingestion.

```APIDOC
## POST /api/v1alpha1/projects/{project_id}/records:batchCreate

### Description
Create multiple audit records in a single request (maximum 100 records per batch) for efficient bulk ingestion.

### Method
POST

### Endpoint
/api/v1alpha1/projects/{project_id}/records:batchCreate

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The unique identifier of the project.

### Request Example
{
  "records": [
    { "resource": { "type": "USER_SESSION", "id": "sess-abc123" }, "operation": { "type": "CREATE" }, "actor": { "type": "USER", "id": "user-100" } }
  ]
}
```