ReportPlaneDocs
WebsiteOpen console

Management API request and response JSON

Complete request and response JSON contracts for every ReportPlane Management API v1 endpoint.

Last verified 2026-08-02

This reference shows the JSON sent to and returned from every endpoint under https://app.reportplane.com/management/v1. It documents the public wire contract—not a language-specific SDK type and not the private session endpoints used by the Dashboard.

Contract conventions

  • JSON request bodies use Content-Type: application/json.
  • Collection routes use project_id, except project listing, which uses workspace_id.
  • IDs are UUID strings.
  • Timestamps are RFC 3339 strings.
  • Collection responses currently return arrays and are not paginated.
  • Stored warehouse credentials, authentication secrets, and encrypted auth_config values are never returned.
  • One-time secrets appear only in the response that creates or generates them.

Projects

List projects

GET/projects
Required scope: projects:read. Success status: 200.

Query parameters

{
  "workspace_id": "WORKSPACE_ID"
}

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": [
    {
      "id": "PROJECT_ID",
      "workspace_id": "WORKSPACE_ID",
      "name": "Production",
      "description": "Production telemetry resources",
      "access_mode": "inherited",
      "created_at": "2026-08-02T10:00:00Z",
      "updated_at": "2026-08-02T10:00:00Z"
    }
  ]
}

Create a project

POST/projects
Required scope: projects:write. Success status: 201.

Request JSON

{
  "workspace_id": "WORKSPACE_ID",
  "name": "Production",
  "description": "Production telemetry resources"
}

Response JSON

{
  "error": false,
  "data": {
    "id": "PROJECT_ID",
    "workspace_id": "WORKSPACE_ID",
    "name": "Production",
    "description": "Production telemetry resources",
    "access_mode": "inherited",
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Get a project

GET/projects/{id}
Required scope: projects:read. Success status: 200.

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "id": "PROJECT_ID",
    "workspace_id": "WORKSPACE_ID",
    "name": "Production",
    "description": "Production telemetry resources",
    "access_mode": "inherited",
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Update a project

PUT/projects/{id}
Required scope: projects:write. Success status: 200.

Request JSON

{
  "name": "Production",
  "description": "Updated description"
}

Response JSON

{
  "error": false,
  "data": {
    "id": "PROJECT_ID",
    "workspace_id": "WORKSPACE_ID",
    "name": "Production",
    "description": "Production telemetry resources",
    "access_mode": "inherited",
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Data models

List models

GET/models
Required scope: models:read. Success status: 200.

Query parameters

{
  "project_id": "PROJECT_ID"
}

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": [
    {
      "id": "MODEL_ID",
      "project_id": "PROJECT_ID",
      "name": "HTTP Requests",
      "key": "http_requests",
      "description": "One record per HTTP request",
      "time_field": "timestamp",
      "enabled": true,
      "fields": [
        {
          "id": "FIELD_ID",
          "schema_id": "MODEL_ID",
          "name": "timestamp",
          "type": "timestamp",
          "required": true,
          "nullable": false,
          "source": "payload",
          "system_key": "",
          "default_value": "",
          "description": "Time at which the event occurred",
          "created_at": "2026-08-02T10:00:00Z",
          "updated_at": "2026-08-02T10:00:00Z"
        }
      ],
      "created_at": "2026-08-02T10:00:00Z",
      "updated_at": "2026-08-02T10:00:00Z"
    }
  ]
}

Create a model

POST/models
Required scope: models:write. Success status: 201.

Request JSON

{
  "project_id": "PROJECT_ID",
  "destination_ids": [
    "WAREHOUSE_ID"
  ],
  "name": "HTTP Requests",
  "key": "http_requests",
  "description": "One record per HTTP request",
  "time_field": "timestamp",
  "fields": [
    {
      "name": "timestamp",
      "type": "timestamp",
      "required": true,
      "nullable": false,
      "source": "payload",
      "system_key": "",
      "default_value": "",
      "description": "Time at which the event occurred"
    }
  ]
}

Accepted values

{
  "fields[].type": [
    "string",
    "int",
    "integer",
    "float",
    "double",
    "number",
    "numeric",
    "bool",
    "boolean",
    "timestamp",
    "datetime",
    "date",
    "json",
    "object",
    "string_array",
    "int_array",
    "integer_array",
    "object_array"
  ],
  "fields[].source": [
    "payload",
    "system",
    "derived"
  ]
}

Response JSON

{
  "error": false,
  "data": {
    "id": "MODEL_ID",
    "project_id": "PROJECT_ID",
    "name": "HTTP Requests",
    "key": "http_requests",
    "description": "One record per HTTP request",
    "time_field": "timestamp",
    "enabled": true,
    "fields": [
      {
        "id": "FIELD_ID",
        "schema_id": "MODEL_ID",
        "name": "timestamp",
        "type": "timestamp",
        "required": true,
        "nullable": false,
        "source": "payload",
        "system_key": "",
        "default_value": "",
        "description": "Time at which the event occurred",
        "created_at": "2026-08-02T10:00:00Z",
        "updated_at": "2026-08-02T10:00:00Z"
      }
    ],
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Get a model

GET/models/{id}
Required scope: models:read. Success status: 200.

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "id": "MODEL_ID",
    "project_id": "PROJECT_ID",
    "name": "HTTP Requests",
    "key": "http_requests",
    "description": "One record per HTTP request",
    "time_field": "timestamp",
    "enabled": true,
    "fields": [
      {
        "id": "FIELD_ID",
        "schema_id": "MODEL_ID",
        "name": "timestamp",
        "type": "timestamp",
        "required": true,
        "nullable": false,
        "source": "payload",
        "system_key": "",
        "default_value": "",
        "description": "Time at which the event occurred",
        "created_at": "2026-08-02T10:00:00Z",
        "updated_at": "2026-08-02T10:00:00Z"
      }
    ],
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Update a model

PUT/models/{id}
Required scope: models:write. Success status: 200.

Request JSON

{
  "name": "HTTP Requests",
  "description": "Updated contract description",
  "time_field": "timestamp",
  "destination_ids": [
    "WAREHOUSE_ID"
  ],
  "fields": [
    {
      "name": "timestamp",
      "type": "timestamp",
      "required": true,
      "nullable": false,
      "source": "payload",
      "system_key": "",
      "default_value": "",
      "description": "Time at which the event occurred"
    }
  ]
}

Accepted values

{
  "fields[].type": [
    "string",
    "int",
    "integer",
    "float",
    "double",
    "number",
    "numeric",
    "bool",
    "boolean",
    "timestamp",
    "datetime",
    "date",
    "json",
    "object",
    "string_array",
    "int_array",
    "integer_array",
    "object_array"
  ],
  "fields[].source": [
    "payload",
    "system",
    "derived"
  ]
}

Response JSON

{
  "error": false,
  "data": {
    "id": "MODEL_ID",
    "project_id": "PROJECT_ID",
    "name": "HTTP Requests",
    "key": "http_requests",
    "description": "One record per HTTP request",
    "time_field": "timestamp",
    "enabled": true,
    "fields": [
      {
        "id": "FIELD_ID",
        "schema_id": "MODEL_ID",
        "name": "timestamp",
        "type": "timestamp",
        "required": true,
        "nullable": false,
        "source": "payload",
        "system_key": "",
        "default_value": "",
        "description": "Time at which the event occurred",
        "created_at": "2026-08-02T10:00:00Z",
        "updated_at": "2026-08-02T10:00:00Z"
      }
    ],
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Archive a model

DELETE/models/{id}
Required scope: models:write. Success status: 200.

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "archived": true
  }
}

Warehouses and credentials

List warehouses

GET/warehouses
Required scope: warehouses:read. Success status: 200.

Query parameters

{
  "project_id": "PROJECT_ID"
}

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": [
    {
      "id": "WAREHOUSE_ID",
      "project_id": "PROJECT_ID",
      "name": "Production BigQuery",
      "type": "bigquery",
      "credential_id": "CREDENTIAL_ID",
      "config": {
        "project_id": "gcp-project",
        "dataset": "reportplane"
      },
      "enabled": true,
      "schema_ids": [
        "MODEL_ID"
      ]
    }
  ]
}

Create a warehouse

POST/warehouses
Required scope: warehouses:write. Success status: 201.

Request JSON

{
  "project_id": "PROJECT_ID",
  "name": "Production BigQuery",
  "type": "bigquery",
  "credential_id": "BIGQUERY_CREDENTIAL_ID",
  "config": {
    "warehouse_mode": "customer",
    "dataset": "analytics",
    "location": "EU",
    "table_strategy": "schema_key",
    "ensure_dataset": true,
    "auto_add_columns": true
  },
  "schema_ids": [
    "MODEL_ID"
  ]
}

Accepted values

{
  "type": [
    "managed",
    "bigquery",
    "clickhouse",
    "snowflake",
    "elasticsearch",
    "opensearch"
  ],
  "config.warehouse_mode": [
    "managed",
    "customer"
  ]
}

Supported request variants

Managed warehouse

ReportPlane selects and provisions the managed BigQuery backend. Do not supply a credential ID.

{
  "project_id": "PROJECT_ID",
  "name": "Managed Warehouse",
  "type": "managed",
  "credential_id": "",
  "config": {
    "warehouse_mode": "managed"
  },
  "schema_ids": [
    "MODEL_ID"
  ]
}
Customer-owned BigQuery
{
  "project_id": "PROJECT_ID",
  "name": "Production BigQuery",
  "type": "bigquery",
  "credential_id": "BIGQUERY_CREDENTIAL_ID",
  "config": {
    "warehouse_mode": "customer",
    "dataset": "analytics",
    "location": "EU",
    "table_strategy": "schema_key",
    "ensure_dataset": true,
    "auto_add_columns": true
  },
  "schema_ids": [
    "MODEL_ID"
  ]
}
ClickHouse
{
  "project_id": "PROJECT_ID",
  "name": "Production ClickHouse",
  "type": "clickhouse",
  "credential_id": "CLICKHOUSE_CREDENTIAL_ID",
  "config": {
    "warehouse_mode": "customer",
    "database": "default",
    "table_strategy": "schema_key",
    "auto_create_table": true,
    "auto_add_columns": true,
    "engine": "MergeTree ORDER BY tuple()"
  },
  "schema_ids": [
    "MODEL_ID"
  ]
}
Snowflake
{
  "project_id": "PROJECT_ID",
  "name": "Production Snowflake",
  "type": "snowflake",
  "credential_id": "SNOWFLAKE_CREDENTIAL_ID",
  "config": {
    "warehouse_mode": "customer",
    "database": "REPORTPLANE",
    "schema": "PUBLIC",
    "table_strategy": "schema_key",
    "auto_create_table": true,
    "auto_add_columns": true
  },
  "schema_ids": [
    "MODEL_ID"
  ]
}
Elasticsearch
{
  "project_id": "PROJECT_ID",
  "name": "Production Elasticsearch",
  "type": "elasticsearch",
  "credential_id": "ELASTICSEARCH_CREDENTIAL_ID",
  "config": {
    "warehouse_mode": "customer",
    "url": "https://elastic.example.com:9200",
    "index_strategy": "schema_key",
    "pipeline": "reportplane-pipeline",
    "auto_create_index": true
  },
  "schema_ids": [
    "MODEL_ID"
  ]
}
OpenSearch
{
  "project_id": "PROJECT_ID",
  "name": "Production OpenSearch",
  "type": "opensearch",
  "credential_id": "OPENSEARCH_CREDENTIAL_ID",
  "config": {
    "warehouse_mode": "customer",
    "url": "https://opensearch.example.com:9200",
    "index_strategy": "schema_key",
    "pipeline": "reportplane-pipeline",
    "auto_create_index": true,
    "opensearch": true
  },
  "schema_ids": [
    "MODEL_ID"
  ]
}

Response JSON

{
  "error": false,
  "data": {
    "id": "WAREHOUSE_ID",
    "project_id": "PROJECT_ID",
    "name": "Production BigQuery",
    "type": "bigquery",
    "credential_id": "CREDENTIAL_ID",
    "config": {
      "project_id": "gcp-project",
      "dataset": "reportplane"
    },
    "enabled": true,
    "schema_ids": [
      "MODEL_ID"
    ]
  }
}

Get a warehouse

GET/warehouses/{id}
Required scope: warehouses:read. Success status: 200.

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "id": "WAREHOUSE_ID",
    "project_id": "PROJECT_ID",
    "name": "Production BigQuery",
    "type": "bigquery",
    "credential_id": "CREDENTIAL_ID",
    "config": {
      "project_id": "gcp-project",
      "dataset": "reportplane"
    },
    "enabled": true,
    "schema_ids": [
      "MODEL_ID"
    ],
    "schemas": [
      {
        "id": "MODEL_ID",
        "name": "HTTP Requests",
        "key": "http_requests",
        "time_field": "timestamp",
        "enabled": true
      }
    ]
  }
}

List warehouse credentials

GET/warehouse-credentials
Required scope: warehouses:read. Success status: 200.

Query parameters

{
  "project_id": "PROJECT_ID"
}

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": [
    {
      "id": "CREDENTIAL_ID",
      "project_id": "PROJECT_ID",
      "name": "BigQuery writer",
      "description": "Production identity",
      "type": "bigquery_service_account",
      "config": "",
      "enabled": true,
      "workspace_shared": false,
      "system": false,
      "created_at": "2026-08-02T10:00:00Z",
      "updated_at": "2026-08-02T10:00:00Z"
    }
  ]
}

Create warehouse credentials

POST/warehouse-credentials
Required scope: warehouses:write. Success status: 201.

Request JSON

{
  "project_id": "PROJECT_ID",
  "name": "BigQuery writer",
  "type": "bigquery",
  "workspace_shared": false,
  "config": {
    "bigquery": {
      "service_account_json": {
        "type": "service_account",
        "project_id": "gcp-project",
        "private_key": "SECRET",
        "client_email": "writer@example.iam.gserviceaccount.com"
      }
    }
  }
}

Accepted values

{
  "type": [
    "bigquery",
    "clickhouse",
    "snowflake",
    "elasticsearch",
    "elasticsearch_basic_auth",
    "elasticsearch_api_key",
    "opensearch"
  ],
  "workspace_shared": [
    false,
    true
  ]
}

Supported request variants

BigQuery service account
{
  "project_id": "PROJECT_ID",
  "name": "BigQuery writer",
  "type": "bigquery",
  "workspace_shared": false,
  "config": {
    "bigquery": {
      "service_account_json": {
        "type": "service_account",
        "project_id": "gcp-project",
        "private_key": "SECRET",
        "client_email": "writer@example.iam.gserviceaccount.com"
      }
    }
  }
}
ClickHouse host credentials

Use host/username/password or provide dsn instead of host.

{
  "project_id": "PROJECT_ID",
  "name": "ClickHouse writer",
  "type": "clickhouse",
  "workspace_shared": false,
  "config": {
    "clickhouse": {
      "host": "clickhouse.example.com:8443",
      "username": "default",
      "password": "SECRET",
      "database": "default",
      "secure": true
    }
  }
}
Snowflake username and password
{
  "project_id": "PROJECT_ID",
  "name": "Snowflake writer",
  "type": "snowflake",
  "workspace_shared": false,
  "config": {
    "snowflake": {
      "account": "ORG-ACCOUNT",
      "username": "REPORTPLANE",
      "password": "SECRET",
      "warehouse": "COMPUTE_WH",
      "role": "REPORTPLANE_WRITER"
    }
  }
}
Elasticsearch basic authentication
{
  "project_id": "PROJECT_ID",
  "name": "Elasticsearch writer",
  "type": "elasticsearch",
  "workspace_shared": false,
  "config": {
    "elasticsearch": {
      "username": "elastic",
      "password": "SECRET"
    }
  }
}
Elasticsearch API key
{
  "project_id": "PROJECT_ID",
  "name": "Elasticsearch API key",
  "type": "elasticsearch_api_key",
  "workspace_shared": false,
  "config": {
    "elasticsearch": {
      "api_key": "SECRET"
    }
  }
}
OpenSearch basic authentication
{
  "project_id": "PROJECT_ID",
  "name": "OpenSearch writer",
  "type": "opensearch",
  "workspace_shared": false,
  "config": {
    "opensearch": {
      "username": "admin",
      "password": "SECRET"
    }
  }
}

Response JSON

{
  "error": false,
  "data": {
    "id": "CREDENTIAL_ID",
    "project_id": "PROJECT_ID",
    "name": "BigQuery writer",
    "description": "Production identity",
    "type": "bigquery_service_account",
    "config": "",
    "enabled": true,
    "workspace_shared": false,
    "system": false,
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

workspace_shared: true requires workspace owner/admin access.

Get warehouse credentials

GET/warehouse-credentials/{id}
Required scope: warehouses:read. Success status: 200.

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "id": "CREDENTIAL_ID",
    "project_id": "PROJECT_ID",
    "name": "BigQuery writer",
    "description": "Production identity",
    "type": "bigquery_service_account",
    "config": "",
    "enabled": true,
    "workspace_shared": false,
    "system": false,
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Update warehouse credentials

PUT/warehouse-credentials/{id}
Required scope: warehouses:write. Success status: 200.

Request JSON

{
  "name": "BigQuery writer",
  "type": "bigquery",
  "config": {
    "bigquery": {
      "service_account_json": {
        "type": "service_account",
        "project_id": "gcp-project",
        "private_key": "SECRET",
        "client_email": "writer@example.iam.gserviceaccount.com"
      }
    }
  },
  "description": "Updated credential",
  "enabled": true
}

Accepted values

{
  "type": [
    "bigquery",
    "clickhouse",
    "snowflake",
    "elasticsearch",
    "elasticsearch_basic_auth",
    "elasticsearch_api_key",
    "opensearch"
  ]
}

Supported request variants

BigQuery service account
{
  "name": "BigQuery writer",
  "type": "bigquery",
  "config": {
    "bigquery": {
      "service_account_json": {
        "type": "service_account",
        "project_id": "gcp-project",
        "private_key": "SECRET",
        "client_email": "writer@example.iam.gserviceaccount.com"
      }
    }
  },
  "description": "Updated credential",
  "enabled": true
}
ClickHouse host credentials

Use host/username/password or provide dsn instead of host.

{
  "name": "ClickHouse writer",
  "type": "clickhouse",
  "config": {
    "clickhouse": {
      "host": "clickhouse.example.com:8443",
      "username": "default",
      "password": "SECRET",
      "database": "default",
      "secure": true
    }
  },
  "description": "Updated credential",
  "enabled": true
}
Snowflake username and password
{
  "name": "Snowflake writer",
  "type": "snowflake",
  "config": {
    "snowflake": {
      "account": "ORG-ACCOUNT",
      "username": "REPORTPLANE",
      "password": "SECRET",
      "warehouse": "COMPUTE_WH",
      "role": "REPORTPLANE_WRITER"
    }
  },
  "description": "Updated credential",
  "enabled": true
}
Elasticsearch basic authentication
{
  "name": "Elasticsearch writer",
  "type": "elasticsearch",
  "config": {
    "elasticsearch": {
      "username": "elastic",
      "password": "SECRET"
    }
  },
  "description": "Updated credential",
  "enabled": true
}
Elasticsearch API key
{
  "name": "Elasticsearch API key",
  "type": "elasticsearch_api_key",
  "config": {
    "elasticsearch": {
      "api_key": "SECRET"
    }
  },
  "description": "Updated credential",
  "enabled": true
}
OpenSearch basic authentication
{
  "name": "OpenSearch writer",
  "type": "opensearch",
  "config": {
    "opensearch": {
      "username": "admin",
      "password": "SECRET"
    }
  },
  "description": "Updated credential",
  "enabled": true
}

Response JSON

{
  "error": false,
  "data": {
    "id": "CREDENTIAL_ID",
    "project_id": "PROJECT_ID",
    "name": "BigQuery writer",
    "description": "Production identity",
    "type": "bigquery_service_account",
    "config": "",
    "enabled": true,
    "workspace_shared": false,
    "system": false,
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Omit config to keep the existing encrypted credential material.

Runtime clients and keys

List ingest clients

GET/ingest-clients
Required scope: clients:read. Success status: 200.

Query parameters

{
  "project_id": "PROJECT_ID"
}

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": [
    {
      "id": "INGEST_CLIENT_ID",
      "project_id": "PROJECT_ID",
      "name": "Web application",
      "description": "Production HTTP events",
      "attributes": {
        "source_type": "http"
      },
      "allowed_schemas": [
        "MODEL_ID"
      ],
      "enabled": true,
      "created_at": "2026-08-02T10:00:00Z",
      "updated_at": "2026-08-02T10:00:00Z"
    }
  ]
}

Create an ingest client

POST/ingest-clients
Required scope: clients:write. Success status: 201.

Request JSON

{
  "project_id": "PROJECT_ID",
  "name": "Web application",
  "description": "Production HTTP events",
  "attributes": {
    "source_type": "http"
  },
  "allowed_schemas": [
    "MODEL_ID"
  ],
  "enabled": true
}

Response JSON

{
  "error": false,
  "data": {
    "id": "INGEST_CLIENT_ID",
    "project_id": "PROJECT_ID",
    "name": "Web application",
    "description": "Production HTTP events",
    "attributes": {
      "source_type": "http"
    },
    "allowed_schemas": [
      "MODEL_ID"
    ],
    "enabled": true,
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Get an ingest client

GET/ingest-clients/{id}
Required scope: clients:read. Success status: 200.

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "client": {
      "id": "INGEST_CLIENT_ID",
      "project_id": "PROJECT_ID",
      "name": "Web application",
      "description": "Production HTTP events",
      "attributes": {
        "source_type": "http"
      },
      "allowed_schemas": [
        "MODEL_ID"
      ],
      "enabled": true,
      "created_at": "2026-08-02T10:00:00Z",
      "updated_at": "2026-08-02T10:00:00Z"
    },
    "authentication": {
      "jwt": {
        "secret_source": "generated"
      },
      "mtls": {
        "ca_id": "CLIENT_CA_ID",
        "identity_source": "uri_san",
        "identity_prefix": "spiffe://example.com/"
      },
      "cidr": {
        "allowed": [
          "203.0.113.0/24"
        ]
      },
      "identity_binding": {
        "mode": "jwt_mtls",
        "jwt_claim": "sub"
      }
    },
    "schemas": [
      {
        "id": "MODEL_ID",
        "name": "HTTP Requests",
        "key": "http_requests"
      }
    ]
  }
}

Update an ingest client

PUT/ingest-clients/{id}
Required scope: clients:write. Success status: 200.

Request JSON

{
  "name": "Web application",
  "description": "Production HTTP events",
  "attributes": {
    "source_type": "http"
  },
  "allowed_schemas": [
    "MODEL_ID"
  ],
  "enabled": true
}

Response JSON

{
  "error": false,
  "data": {
    "id": "INGEST_CLIENT_ID",
    "project_id": "PROJECT_ID",
    "name": "Web application",
    "description": "Production HTTP events",
    "attributes": {
      "source_type": "http"
    },
    "allowed_schemas": [
      "MODEL_ID"
    ],
    "enabled": true,
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Delete an ingest client

DELETE/ingest-clients/{id}
Required scope: clients:write. Success status: 200.

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "deleted": true
  }
}

Configure ingest authentication

PUT/ingest-clients/{id}/authentication
Required scope: clients:write. Success status: 200.

Request JSON

{
  "config": {
    "jwt": {
      "secret_source": "generated",
      "secret": ""
    },
    "mtls": {
      "ca_id": "CLIENT_CA_ID",
      "identity_source": "uri_san",
      "identity_prefix": "spiffe://example.com/"
    },
    "cidr": {
      "allowed": [
        "203.0.113.0/24"
      ]
    },
    "identity_binding": {
      "mode": "jwt_mtls",
      "jwt_claim": "sub"
    }
  }
}

Accepted values

{
  "config.jwt.secret_source": [
    "generated",
    "customer"
  ],
  "config.mtls.identity_source": [
    "uri_san"
  ],
  "config.identity_binding.mode": [
    "none",
    "jwt_payload",
    "jwt_payload_mtls",
    "jwt_mtls"
  ]
}

Supported request variants

Generated JWT secret

The generated secret is returned once in data.generated_secret.

{
  "config": {
    "jwt": {
      "secret_source": "generated",
      "secret": ""
    }
  }
}
Customer-provided JWT secret
{
  "config": {
    "jwt": {
      "secret_source": "customer",
      "secret": "CUSTOMER_SECRET"
    }
  }
}
mTLS with CIDR restriction
{
  "config": {
    "mtls": {
      "ca_id": "CLIENT_CA_ID",
      "identity_source": "uri_san",
      "identity_prefix": "spiffe://example.com/"
    },
    "cidr": {
      "allowed": [
        "203.0.113.0/24"
      ]
    }
  }
}
JWT payload binding
{
  "config": {
    "jwt": {
      "secret_source": "customer",
      "secret": "CUSTOMER_SECRET"
    },
    "identity_binding": {
      "mode": "jwt_payload",
      "jwt_claim": "sub",
      "payload_field": "customer_id"
    }
  }
}
JWT and mTLS identity binding
{
  "config": {
    "jwt": {
      "secret_source": "customer",
      "secret": "CUSTOMER_SECRET"
    },
    "mtls": {
      "ca_id": "CLIENT_CA_ID",
      "identity_source": "uri_san",
      "identity_prefix": "spiffe://example.com/"
    },
    "identity_binding": {
      "mode": "jwt_mtls",
      "jwt_claim": "sub"
    }
  }
}

Response JSON

{
  "error": false,
  "data": {
    "generated_secret": "ONE_TIME_SECRET"
  }
}

generated_secret is omitted when no secret was generated and is never returned again.

List query clients

GET/query-clients
Required scope: clients:read. Success status: 200.

Query parameters

{
  "project_id": "PROJECT_ID"
}

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": [
    {
      "id": "QUERY_CLIENT_ID",
      "project_id": "PROJECT_ID",
      "name": "Customer dashboard",
      "description": "Read identity for the customer dashboard",
      "allowed_analytics": [
        "ANALYTICS_API_ID"
      ],
      "access_filters": [],
      "max_range_days": 30,
      "max_rps": 10,
      "allow_delegation": false,
      "delegation_ttl_seconds": 3600,
      "time_restriction_enabled": false,
      "allowed_time_windows": "Mon-Fri 09:00-18:00",
      "timezone": "UTC",
      "enabled": true,
      "created_at": "2026-08-02T10:00:00Z",
      "updated_at": "2026-08-02T10:00:00Z"
    }
  ]
}

Create a query client

POST/query-clients
Required scope: clients:write. Success status: 201.

Request JSON

{
  "project_id": "PROJECT_ID",
  "name": "Customer dashboard",
  "description": "Read identity for the customer dashboard",
  "allowed_analytics": [
    "ANALYTICS_API_ID"
  ],
  "access_filters": [],
  "max_range_days": 30,
  "max_rps": 10,
  "allow_delegation": false,
  "delegation_ttl_seconds": 3600,
  "time_restriction_enabled": false,
  "allowed_time_windows": "Mon-Fri 09:00-18:00",
  "timezone": "UTC",
  "enabled": true
}

Accepted values

{
  "access_filters[].operator": [
    "equals",
    "not_equals",
    "contains",
    "not_contains",
    "in",
    "not_in",
    "between",
    "gt",
    "gte",
    "lt",
    "lte",
    "exists",
    "contains_any",
    "contains_all"
  ],
  "timezone": [
    "IANA timezone, for example UTC or Europe/Istanbul"
  ]
}

Response JSON

{
  "error": false,
  "data": {
    "id": "QUERY_CLIENT_ID",
    "project_id": "PROJECT_ID",
    "name": "Customer dashboard",
    "description": "Read identity for the customer dashboard",
    "allowed_analytics": [
      "ANALYTICS_API_ID"
    ],
    "access_filters": [],
    "max_range_days": 30,
    "max_rps": 10,
    "allow_delegation": false,
    "delegation_ttl_seconds": 3600,
    "time_restriction_enabled": false,
    "allowed_time_windows": "Mon-Fri 09:00-18:00",
    "timezone": "UTC",
    "enabled": true,
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Get a query client

GET/query-clients/{id}
Required scope: clients:read. Success status: 200.

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "client": {
      "id": "QUERY_CLIENT_ID",
      "project_id": "PROJECT_ID",
      "name": "Customer dashboard",
      "description": "Read identity for the customer dashboard",
      "allowed_analytics": [
        "ANALYTICS_API_ID"
      ],
      "access_filters": [],
      "max_range_days": 30,
      "max_rps": 10,
      "allow_delegation": false,
      "delegation_ttl_seconds": 3600,
      "time_restriction_enabled": false,
      "allowed_time_windows": "Mon-Fri 09:00-18:00",
      "timezone": "UTC",
      "enabled": true,
      "created_at": "2026-08-02T10:00:00Z",
      "updated_at": "2026-08-02T10:00:00Z"
    },
    "authentication": {
      "jwt": {
        "secret_source": "generated"
      },
      "mtls": {
        "ca_id": "CLIENT_CA_ID",
        "identity_source": "uri_san",
        "identity_prefix": "spiffe://example.com/"
      },
      "cidr": {
        "allowed": [
          "203.0.113.0/24"
        ]
      },
      "identity_binding": {
        "mode": "jwt_mtls",
        "jwt_claim": "sub"
      }
    },
    "analytics": [
      {
        "id": "ANALYTICS_API_ID",
        "name": "Requests by status",
        "key": "requests_by_status"
      }
    ]
  }
}

Update a query client

PUT/query-clients/{id}
Required scope: clients:write. Success status: 200.

Request JSON

{
  "name": "Customer dashboard",
  "description": "Read identity for the customer dashboard",
  "allowed_analytics": [
    "ANALYTICS_API_ID"
  ],
  "access_filters": [],
  "max_range_days": 30,
  "max_rps": 10,
  "allow_delegation": false,
  "delegation_ttl_seconds": 3600,
  "time_restriction_enabled": false,
  "allowed_time_windows": "Mon-Fri 09:00-18:00",
  "timezone": "UTC",
  "enabled": true
}

Accepted values

{
  "access_filters[].operator": [
    "equals",
    "not_equals",
    "contains",
    "not_contains",
    "in",
    "not_in",
    "between",
    "gt",
    "gte",
    "lt",
    "lte",
    "exists",
    "contains_any",
    "contains_all"
  ],
  "timezone": [
    "IANA timezone, for example UTC or Europe/Istanbul"
  ]
}

Response JSON

{
  "error": false,
  "data": {
    "id": "QUERY_CLIENT_ID",
    "project_id": "PROJECT_ID",
    "name": "Customer dashboard",
    "description": "Read identity for the customer dashboard",
    "allowed_analytics": [
      "ANALYTICS_API_ID"
    ],
    "access_filters": [],
    "max_range_days": 30,
    "max_rps": 10,
    "allow_delegation": false,
    "delegation_ttl_seconds": 3600,
    "time_restriction_enabled": false,
    "allowed_time_windows": "Mon-Fri 09:00-18:00",
    "timezone": "UTC",
    "enabled": true,
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Delete a query client

DELETE/query-clients/{id}
Required scope: clients:write. Success status: 200.

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "deleted": true
  }
}

Configure query authentication

PUT/query-clients/{id}/authentication
Required scope: clients:write. Success status: 200.

Request JSON

{
  "config": {
    "jwt": {
      "secret_source": "generated",
      "secret": ""
    },
    "mtls": {
      "ca_id": "CLIENT_CA_ID",
      "identity_source": "uri_san",
      "identity_prefix": "spiffe://example.com/"
    },
    "cidr": {
      "allowed": [
        "203.0.113.0/24"
      ]
    },
    "identity_binding": {
      "mode": "jwt_mtls",
      "jwt_claim": "sub"
    }
  }
}

Accepted values

{
  "config.jwt.secret_source": [
    "generated",
    "customer"
  ],
  "config.mtls.identity_source": [
    "uri_san"
  ],
  "config.identity_binding.mode": [
    "none",
    "jwt_payload",
    "jwt_payload_mtls",
    "jwt_mtls"
  ]
}

Supported request variants

Generated JWT secret

The generated secret is returned once in data.generated_secret.

{
  "config": {
    "jwt": {
      "secret_source": "generated",
      "secret": ""
    }
  }
}
Customer-provided JWT secret
{
  "config": {
    "jwt": {
      "secret_source": "customer",
      "secret": "CUSTOMER_SECRET"
    }
  }
}
mTLS with CIDR restriction
{
  "config": {
    "mtls": {
      "ca_id": "CLIENT_CA_ID",
      "identity_source": "uri_san",
      "identity_prefix": "spiffe://example.com/"
    },
    "cidr": {
      "allowed": [
        "203.0.113.0/24"
      ]
    }
  }
}
JWT payload binding
{
  "config": {
    "jwt": {
      "secret_source": "customer",
      "secret": "CUSTOMER_SECRET"
    },
    "identity_binding": {
      "mode": "jwt_payload",
      "jwt_claim": "sub",
      "payload_field": "customer_id"
    }
  }
}
JWT and mTLS identity binding
{
  "config": {
    "jwt": {
      "secret_source": "customer",
      "secret": "CUSTOMER_SECRET"
    },
    "mtls": {
      "ca_id": "CLIENT_CA_ID",
      "identity_source": "uri_san",
      "identity_prefix": "spiffe://example.com/"
    },
    "identity_binding": {
      "mode": "jwt_mtls",
      "jwt_claim": "sub"
    }
  }
}

Response JSON

{
  "error": false,
  "data": {
    "generated_secret": "ONE_TIME_SECRET"
  }
}

generated_secret is omitted when no secret was generated and is never returned again.

List Runtime API Keys

GET/runtime-api-keys
Required scope: clients:read. Success status: 200.

Query parameters

{
  "project_id": "PROJECT_ID"
}

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": [
    {
      "id": "RUNTIME_API_KEY_ID",
      "project_id": "PROJECT_ID",
      "name": "Application runtime key",
      "description": "Ingest-only production credential",
      "allow_ingest": true,
      "allow_query": false,
      "allowed_schemas": [
        "MODEL_ID"
      ],
      "allowed_analytics": [],
      "allowed_ips": [
        "203.0.113.0/24"
      ],
      "key_prefix": "rp_ak_abcd1234",
      "enabled": true,
      "created_by_user_id": "USER_ID",
      "last_used_at": null,
      "last_used_ip": "",
      "revoked_at": null,
      "created_at": "2026-08-02T10:00:00Z",
      "updated_at": "2026-08-02T10:00:00Z"
    }
  ]
}

Create a Runtime API Key

POST/runtime-api-keys
Required scope: clients:write. Success status: 201.

Request JSON

{
  "project_id": "PROJECT_ID",
  "name": "Application runtime key",
  "description": "Ingest-only production credential",
  "allow_ingest": true,
  "allow_query": false,
  "allowed_schemas": [
    "MODEL_ID"
  ],
  "allowed_analytics": [],
  "allowed_ips": [
    "203.0.113.0/24"
  ],
  "enabled": true
}

Supported request variants

Ingest only
{
  "project_id": "PROJECT_ID",
  "name": "Application runtime key",
  "description": "Ingest-only production credential",
  "allow_ingest": true,
  "allow_query": false,
  "allowed_schemas": [
    "MODEL_ID"
  ],
  "allowed_analytics": [],
  "allowed_ips": [
    "203.0.113.0/24"
  ],
  "enabled": true
}
Query only
{
  "project_id": "PROJECT_ID",
  "name": "Application runtime key",
  "description": "Ingest-only production credential",
  "allow_ingest": false,
  "allow_query": true,
  "allowed_schemas": [],
  "allowed_analytics": [
    "ANALYTICS_API_ID"
  ],
  "allowed_ips": [
    "203.0.113.0/24"
  ],
  "enabled": true
}
Ingest and query
{
  "project_id": "PROJECT_ID",
  "name": "Application runtime key",
  "description": "Ingest-only production credential",
  "allow_ingest": true,
  "allow_query": true,
  "allowed_schemas": [
    "MODEL_ID"
  ],
  "allowed_analytics": [
    "ANALYTICS_API_ID"
  ],
  "allowed_ips": [
    "203.0.113.0/24"
  ],
  "enabled": true
}

Response JSON

{
  "error": false,
  "data": {
    "api_key": {
      "id": "RUNTIME_API_KEY_ID",
      "project_id": "PROJECT_ID",
      "name": "Application runtime key",
      "description": "Ingest-only production credential",
      "allow_ingest": true,
      "allow_query": false,
      "allowed_schemas": [
        "MODEL_ID"
      ],
      "allowed_analytics": [],
      "allowed_ips": [
        "203.0.113.0/24"
      ],
      "key_prefix": "rp_ak_abcd1234",
      "enabled": true,
      "created_by_user_id": "USER_ID",
      "last_used_at": null,
      "last_used_ip": "",
      "revoked_at": null,
      "created_at": "2026-08-02T10:00:00Z",
      "updated_at": "2026-08-02T10:00:00Z"
    },
    "secret": "rp_ak_abcd1234.ONE_TIME_SECRET"
  }
}

secret is returned once.

Get a Runtime API Key

GET/runtime-api-keys/{id}
Required scope: clients:read. Success status: 200.

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "api_key": {
      "id": "RUNTIME_API_KEY_ID",
      "project_id": "PROJECT_ID",
      "name": "Application runtime key",
      "description": "Ingest-only production credential",
      "allow_ingest": true,
      "allow_query": false,
      "allowed_schemas": [
        "MODEL_ID"
      ],
      "allowed_analytics": [],
      "allowed_ips": [
        "203.0.113.0/24"
      ],
      "key_prefix": "rp_ak_abcd1234",
      "enabled": true,
      "created_by_user_id": "USER_ID",
      "last_used_at": null,
      "last_used_ip": "",
      "revoked_at": null,
      "created_at": "2026-08-02T10:00:00Z",
      "updated_at": "2026-08-02T10:00:00Z"
    }
  }
}

Update a Runtime API Key

PUT/runtime-api-keys/{id}
Required scope: clients:write. Success status: 200.

Request JSON

{
  "name": "Application runtime key",
  "description": "Ingest-only production credential",
  "allow_ingest": true,
  "allow_query": false,
  "allowed_schemas": [
    "MODEL_ID"
  ],
  "allowed_analytics": [],
  "allowed_ips": [
    "203.0.113.0/24"
  ],
  "enabled": true
}

Supported request variants

Ingest only
{
  "name": "Application runtime key",
  "description": "Ingest-only production credential",
  "allow_ingest": true,
  "allow_query": false,
  "allowed_schemas": [
    "MODEL_ID"
  ],
  "allowed_analytics": [],
  "allowed_ips": [
    "203.0.113.0/24"
  ],
  "enabled": true
}
Query only
{
  "name": "Application runtime key",
  "description": "Ingest-only production credential",
  "allow_ingest": false,
  "allow_query": true,
  "allowed_schemas": [],
  "allowed_analytics": [
    "ANALYTICS_API_ID"
  ],
  "allowed_ips": [
    "203.0.113.0/24"
  ],
  "enabled": true
}
Ingest and query
{
  "name": "Application runtime key",
  "description": "Ingest-only production credential",
  "allow_ingest": true,
  "allow_query": true,
  "allowed_schemas": [
    "MODEL_ID"
  ],
  "allowed_analytics": [
    "ANALYTICS_API_ID"
  ],
  "allowed_ips": [
    "203.0.113.0/24"
  ],
  "enabled": true
}

Response JSON

{
  "error": false,
  "data": {
    "id": "RUNTIME_API_KEY_ID",
    "project_id": "PROJECT_ID",
    "name": "Application runtime key",
    "description": "Ingest-only production credential",
    "allow_ingest": true,
    "allow_query": false,
    "allowed_schemas": [
      "MODEL_ID"
    ],
    "allowed_analytics": [],
    "allowed_ips": [
      "203.0.113.0/24"
    ],
    "key_prefix": "rp_ak_abcd1234",
    "enabled": true,
    "created_by_user_id": "USER_ID",
    "last_used_at": null,
    "last_used_ip": "",
    "revoked_at": null,
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Revoke a Runtime API Key

DELETE/runtime-api-keys/{id}
Required scope: clients:write. Success status: 200.

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "revoked": true
  }
}

Analytics APIs and bindings

List Analytics APIs

GET/analytics-apis
Required scope: analytics:read. Success status: 200.

Query parameters

{
  "project_id": "PROJECT_ID"
}

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": [
    {
      "id": "ANALYTICS_API_ID",
      "project_id": "PROJECT_ID",
      "schema_id": "MODEL_ID",
      "name": "Requests by status",
      "key": "requests_by_status",
      "description": "Count requests grouped by status code",
      "definition": {
        "parameters": [],
        "dimensions": [
          {
            "field": "status_code",
            "alias": "status_code"
          }
        ],
        "metrics": [
          {
            "aggregation": "count",
            "alias": "request_count"
          }
        ],
        "fixed_filters": [],
        "allowed_filters": [
          {
            "field": "timestamp",
            "operators": [
              "between",
              "gte",
              "lte"
            ]
          }
        ],
        "latest_by": {
          "partition_by": [
            "request_id"
          ],
          "order_by": [
            {
              "field": "timestamp",
              "direction": "desc"
            }
          ]
        },
        "order_by": [
          {
            "field": "request_count",
            "direction": "desc"
          }
        ],
        "limit": 100,
        "visualization": {
          "x_key": "status_code",
          "y_keys": [
            "request_count"
          ]
        }
      },
      "chart_type": "bar",
      "published": true,
      "enabled": true,
      "created_at": "2026-08-02T10:00:00Z",
      "updated_at": "2026-08-02T10:00:00Z",
      "schema": {
        "id": "MODEL_ID",
        "name": "HTTP Requests",
        "key": "http_requests"
      },
      "usage": {
        "requests_today": 0,
        "avg_latency_ms": 0,
        "cache_hits": 0,
        "cache_misses": 0,
        "cost_today_usd": 0
      },
      "bindings": [
        {
          "id": "BINDING_ID",
          "project_id": "PROJECT_ID",
          "analytics_id": "ANALYTICS_API_ID",
          "destination_id": "WAREHOUSE_ID",
          "backend_type": "bigquery",
          "preferred": true,
          "enabled": true,
          "cache_ttl_seconds": 300,
          "max_rows": 10000,
          "created_at": "2026-08-02T10:00:00Z",
          "updated_at": "2026-08-02T10:00:00Z"
        }
      ]
    }
  ]
}

Create an Analytics API

POST/analytics-apis
Required scope: analytics:write. Success status: 201.

Request JSON

{
  "project_id": "PROJECT_ID",
  "schema_id": "MODEL_ID",
  "name": "Requests by status",
  "key": "requests_by_status",
  "description": "Count requests grouped by status code",
  "definition": {
    "parameters": [],
    "dimensions": [
      {
        "field": "status_code",
        "alias": "status_code"
      }
    ],
    "metrics": [
      {
        "aggregation": "count",
        "alias": "request_count"
      }
    ],
    "fixed_filters": [],
    "allowed_filters": [
      {
        "field": "timestamp",
        "operators": [
          "between",
          "gte",
          "lte"
        ]
      }
    ],
    "latest_by": {
      "partition_by": [
        "request_id"
      ],
      "order_by": [
        {
          "field": "timestamp",
          "direction": "desc"
        }
      ]
    },
    "order_by": [
      {
        "field": "request_count",
        "direction": "desc"
      }
    ],
    "limit": 100,
    "visualization": {
      "x_key": "status_code",
      "y_keys": [
        "request_count"
      ]
    }
  },
  "chart_type": "bar",
  "published": true
}

Accepted values

{
  "chart_type": [
    "table",
    "number",
    "line",
    "area",
    "bar",
    "horizontal_bar",
    "stacked_bar",
    "pie",
    "doughnut",
    "scatter",
    "map",
    "histogram",
    "funnel",
    "cohort_heatmap",
    "combo_bar_line"
  ],
  "definition.parameters[].type": [
    "string",
    "int",
    "integer",
    "float",
    "double",
    "bool",
    "boolean",
    "datetime",
    "timestamp"
  ],
  "definition.dimensions[].bucket": [
    "minute",
    "hour",
    "day",
    "week",
    "month"
  ],
  "definition.dimensions[].array_format": [
    "array",
    "join"
  ],
  "definition.metrics[].aggregation": [
    "count",
    "sum",
    "avg",
    "min",
    "max",
    "distinct_count"
  ],
  "definition.fixed_filters[].operator": [
    "equals",
    "not_equals",
    "contains",
    "not_contains",
    "in",
    "not_in",
    "between",
    "gt",
    "gte",
    "lt",
    "lte",
    "exists",
    "contains_any",
    "contains_all"
  ],
  "definition.order_by[].direction": [
    "asc",
    "desc"
  ],
  "definition.latest_by.order_by[].direction": [
    "asc",
    "desc"
  ],
  "definition.visualization.stack_mode": [
    "none",
    "normal",
    "percent"
  ]
}

Response JSON

{
  "error": false,
  "data": {
    "id": "ANALYTICS_API_ID",
    "project_id": "PROJECT_ID",
    "schema_id": "MODEL_ID",
    "name": "Requests by status",
    "key": "requests_by_status",
    "description": "Count requests grouped by status code",
    "definition": {
      "parameters": [],
      "dimensions": [
        {
          "field": "status_code",
          "alias": "status_code"
        }
      ],
      "metrics": [
        {
          "aggregation": "count",
          "alias": "request_count"
        }
      ],
      "fixed_filters": [],
      "allowed_filters": [
        {
          "field": "timestamp",
          "operators": [
            "between",
            "gte",
            "lte"
          ]
        }
      ],
      "latest_by": {
        "partition_by": [
          "request_id"
        ],
        "order_by": [
          {
            "field": "timestamp",
            "direction": "desc"
          }
        ]
      },
      "order_by": [
        {
          "field": "request_count",
          "direction": "desc"
        }
      ],
      "limit": 100,
      "visualization": {
        "x_key": "status_code",
        "y_keys": [
          "request_count"
        ]
      }
    },
    "chart_type": "bar",
    "published": true,
    "enabled": true,
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Get an Analytics API

GET/analytics-apis/{id}
Required scope: analytics:read. Success status: 200.

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "id": "ANALYTICS_API_ID",
    "project_id": "PROJECT_ID",
    "schema_id": "MODEL_ID",
    "name": "Requests by status",
    "key": "requests_by_status",
    "description": "Count requests grouped by status code",
    "definition": {
      "parameters": [],
      "dimensions": [
        {
          "field": "status_code",
          "alias": "status_code"
        }
      ],
      "metrics": [
        {
          "aggregation": "count",
          "alias": "request_count"
        }
      ],
      "fixed_filters": [],
      "allowed_filters": [
        {
          "field": "timestamp",
          "operators": [
            "between",
            "gte",
            "lte"
          ]
        }
      ],
      "latest_by": {
        "partition_by": [
          "request_id"
        ],
        "order_by": [
          {
            "field": "timestamp",
            "direction": "desc"
          }
        ]
      },
      "order_by": [
        {
          "field": "request_count",
          "direction": "desc"
        }
      ],
      "limit": 100,
      "visualization": {
        "x_key": "status_code",
        "y_keys": [
          "request_count"
        ]
      }
    },
    "chart_type": "bar",
    "published": true,
    "enabled": true,
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z",
    "schema": {
      "id": "MODEL_ID",
      "name": "HTTP Requests",
      "key": "http_requests"
    },
    "usage": {
      "requests_today": 0,
      "avg_latency_ms": 0,
      "cache_hits": 0,
      "cache_misses": 0,
      "cost_today_usd": 0
    },
    "bindings": [
      {
        "id": "BINDING_ID",
        "project_id": "PROJECT_ID",
        "analytics_id": "ANALYTICS_API_ID",
        "destination_id": "WAREHOUSE_ID",
        "backend_type": "bigquery",
        "preferred": true,
        "enabled": true,
        "cache_ttl_seconds": 300,
        "max_rows": 10000,
        "created_at": "2026-08-02T10:00:00Z",
        "updated_at": "2026-08-02T10:00:00Z"
      }
    ]
  }
}

Update an Analytics API

PUT/analytics-apis/{id}
Required scope: analytics:write. Success status: 200.

Request JSON

{
  "name": "Requests by status",
  "description": "Count requests grouped by status code",
  "definition": {
    "parameters": [],
    "dimensions": [
      {
        "field": "status_code",
        "alias": "status_code"
      }
    ],
    "metrics": [
      {
        "aggregation": "count",
        "alias": "request_count"
      }
    ],
    "fixed_filters": [],
    "allowed_filters": [
      {
        "field": "timestamp",
        "operators": [
          "between",
          "gte",
          "lte"
        ]
      }
    ],
    "latest_by": {
      "partition_by": [
        "request_id"
      ],
      "order_by": [
        {
          "field": "timestamp",
          "direction": "desc"
        }
      ]
    },
    "order_by": [
      {
        "field": "request_count",
        "direction": "desc"
      }
    ],
    "limit": 100,
    "visualization": {
      "x_key": "status_code",
      "y_keys": [
        "request_count"
      ]
    }
  },
  "chart_type": "bar",
  "published": true
}

Accepted values

{
  "chart_type": [
    "table",
    "number",
    "line",
    "area",
    "bar",
    "horizontal_bar",
    "stacked_bar",
    "pie",
    "doughnut",
    "scatter",
    "map",
    "histogram",
    "funnel",
    "cohort_heatmap",
    "combo_bar_line"
  ],
  "definition.parameters[].type": [
    "string",
    "int",
    "integer",
    "float",
    "double",
    "bool",
    "boolean",
    "datetime",
    "timestamp"
  ],
  "definition.dimensions[].bucket": [
    "minute",
    "hour",
    "day",
    "week",
    "month"
  ],
  "definition.dimensions[].array_format": [
    "array",
    "join"
  ],
  "definition.metrics[].aggregation": [
    "count",
    "sum",
    "avg",
    "min",
    "max",
    "distinct_count"
  ],
  "definition.fixed_filters[].operator": [
    "equals",
    "not_equals",
    "contains",
    "not_contains",
    "in",
    "not_in",
    "between",
    "gt",
    "gte",
    "lt",
    "lte",
    "exists",
    "contains_any",
    "contains_all"
  ],
  "definition.order_by[].direction": [
    "asc",
    "desc"
  ],
  "definition.latest_by.order_by[].direction": [
    "asc",
    "desc"
  ],
  "definition.visualization.stack_mode": [
    "none",
    "normal",
    "percent"
  ]
}

Response JSON

{
  "error": false,
  "data": {
    "id": "ANALYTICS_API_ID",
    "project_id": "PROJECT_ID",
    "schema_id": "MODEL_ID",
    "name": "Requests by status",
    "key": "requests_by_status",
    "description": "Count requests grouped by status code",
    "definition": {
      "parameters": [],
      "dimensions": [
        {
          "field": "status_code",
          "alias": "status_code"
        }
      ],
      "metrics": [
        {
          "aggregation": "count",
          "alias": "request_count"
        }
      ],
      "fixed_filters": [],
      "allowed_filters": [
        {
          "field": "timestamp",
          "operators": [
            "between",
            "gte",
            "lte"
          ]
        }
      ],
      "latest_by": {
        "partition_by": [
          "request_id"
        ],
        "order_by": [
          {
            "field": "timestamp",
            "direction": "desc"
          }
        ]
      },
      "order_by": [
        {
          "field": "request_count",
          "direction": "desc"
        }
      ],
      "limit": 100,
      "visualization": {
        "x_key": "status_code",
        "y_keys": [
          "request_count"
        ]
      }
    },
    "chart_type": "bar",
    "published": true,
    "enabled": true,
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z",
    "schema": {
      "id": "MODEL_ID",
      "name": "HTTP Requests",
      "key": "http_requests"
    },
    "usage": {
      "requests_today": 0,
      "avg_latency_ms": 0,
      "cache_hits": 0,
      "cache_misses": 0,
      "cost_today_usd": 0
    },
    "bindings": [
      {
        "id": "BINDING_ID",
        "project_id": "PROJECT_ID",
        "analytics_id": "ANALYTICS_API_ID",
        "destination_id": "WAREHOUSE_ID",
        "backend_type": "bigquery",
        "preferred": true,
        "enabled": true,
        "cache_ttl_seconds": 300,
        "max_rows": 10000,
        "created_at": "2026-08-02T10:00:00Z",
        "updated_at": "2026-08-02T10:00:00Z"
      }
    ]
  }
}

Archive an Analytics API

DELETE/analytics-apis/{id}
Required scope: analytics:write. Success status: 200.

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "archived": true
  }
}

List analytics bindings

GET/analytics-bindings
Required scope: analytics:read. Success status: 200.

Query parameters

{
  "project_id": "PROJECT_ID"
}

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": [
    {
      "id": "BINDING_ID",
      "project_id": "PROJECT_ID",
      "analytics_id": "ANALYTICS_API_ID",
      "destination_id": "WAREHOUSE_ID",
      "backend_type": "bigquery",
      "preferred": true,
      "enabled": true,
      "cache_ttl_seconds": 300,
      "max_rows": 10000,
      "created_at": "2026-08-02T10:00:00Z",
      "updated_at": "2026-08-02T10:00:00Z"
    }
  ]
}

Create an analytics binding

POST/analytics-bindings
Required scope: analytics:write. Success status: 201.

Request JSON

{
  "project_id": "PROJECT_ID",
  "analytics_id": "ANALYTICS_API_ID",
  "destination_id": "WAREHOUSE_ID",
  "backend_type": "bigquery",
  "preferred": true,
  "cache_ttl_seconds": 300,
  "max_rows": 10000
}

Accepted values

{
  "backend_type": [
    "bigquery",
    "clickhouse",
    "snowflake",
    "elasticsearch",
    "opensearch"
  ]
}

Response JSON

{
  "error": false,
  "data": {
    "id": "BINDING_ID",
    "project_id": "PROJECT_ID",
    "analytics_id": "ANALYTICS_API_ID",
    "destination_id": "WAREHOUSE_ID",
    "backend_type": "bigquery",
    "preferred": true,
    "enabled": true,
    "cache_ttl_seconds": 300,
    "max_rows": 10000,
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Promote an analytics binding

POST/analytics-bindings/{id}/promote
Required scope: analytics:write. Success status: 200.

Request JSON

{
  "project_id": "PROJECT_ID"
}

Response JSON

{
  "error": false,
  "data": {
    "id": "BINDING_ID",
    "project_id": "PROJECT_ID",
    "analytics_id": "ANALYTICS_API_ID",
    "destination_id": "WAREHOUSE_ID",
    "backend_type": "bigquery",
    "preferred": true,
    "enabled": true,
    "cache_ttl_seconds": 300,
    "max_rows": 10000,
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Atomically clears preferred on the Analytics API's other bindings, then enables and promotes this binding. Existing bindings are retained for rollback.

Shared datasets

List shared datasets

GET/datasets
Required scope: datasets:read. Success status: 200.

Query parameters

{
  "project_id": "PROJECT_ID",
  "destination_id": "WAREHOUSE_ID"
}

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": [
    {
      "id": "DATASET_ID",
      "project_id": "PROJECT_ID",
      "destination_id": "WAREHOUSE_ID",
      "name": "Global Cloud Reliability",
      "slug": "cloud-service-reliability",
      "description": "Public cloud service incidents and component health.",
      "status": "draft",
      "visibility": "unlisted",
      "catalog_status": "not_submitted",
      "source_name": "Public provider status APIs",
      "source_url": "https://example.com/status",
      "license_name": "Source terms",
      "license_url": "https://example.com/terms",
      "attribution": "Public provider status APIs",
      "warehouse": {
        "id": "WAREHOUSE_ID",
        "name": "Public Data · cloud-service-reliability",
        "type": "bigquery",
        "enabled": true
      },
      "models": [
        {
          "id": "MODEL_ID",
          "name": "Cloud incidents",
          "key": "cloud_service_incidents",
          "time_field": "observed_at",
          "enabled": true,
          "fields": []
        }
      ],
      "charts": [
        {
          "id": "ANALYTICS_API_ID",
          "key": "cloud_incidents_daily",
          "name": "Cloud incidents by day",
          "description": "Incident flow by day",
          "chart_type": "line",
          "updated_at": "2026-08-02T10:00:00Z"
        }
      ],
      "created_at": "2026-08-02T10:00:00Z",
      "updated_at": "2026-08-02T10:00:00Z"
    }
  ]
}

Create a shared dataset

POST/datasets
Required scope: datasets:write. Success status: 201.

Request JSON

{
  "project_id": "PROJECT_ID",
  "destination_id": "WAREHOUSE_ID",
  "name": "Global Cloud Reliability",
  "slug": "cloud-service-reliability",
  "description": "Public cloud service incidents and component health.",
  "status": "draft",
  "visibility": "unlisted",
  "schema_ids": [
    "MODEL_ID"
  ],
  "analytics_ids": [
    "ANALYTICS_API_ID"
  ],
  "source_name": "Public provider status APIs",
  "source_url": "https://example.com/status",
  "license_name": "Source terms",
  "license_url": "https://example.com/terms",
  "attribution": "Public provider status APIs"
}

Accepted values

{
  "status": [
    "draft",
    "published",
    "disabled"
  ],
  "visibility": [
    "unlisted",
    "public"
  ]
}

Response JSON

{
  "error": false,
  "data": {
    "id": "DATASET_ID",
    "project_id": "PROJECT_ID",
    "destination_id": "WAREHOUSE_ID",
    "name": "Global Cloud Reliability",
    "slug": "cloud-service-reliability",
    "description": "Public cloud service incidents and component health.",
    "status": "draft",
    "visibility": "unlisted",
    "catalog_status": "not_submitted",
    "source_name": "Public provider status APIs",
    "source_url": "https://example.com/status",
    "license_name": "Source terms",
    "license_url": "https://example.com/terms",
    "attribution": "Public provider status APIs",
    "warehouse": {
      "id": "WAREHOUSE_ID",
      "name": "Public Data · cloud-service-reliability",
      "type": "bigquery",
      "enabled": true
    },
    "models": [
      {
        "id": "MODEL_ID",
        "name": "Cloud incidents",
        "key": "cloud_service_incidents",
        "time_field": "observed_at",
        "enabled": true,
        "fields": []
      }
    ],
    "charts": [
      {
        "id": "ANALYTICS_API_ID",
        "key": "cloud_incidents_daily",
        "name": "Cloud incidents by day",
        "description": "Incident flow by day",
        "chart_type": "line",
        "updated_at": "2026-08-02T10:00:00Z"
      }
    ],
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Automation should create draft/unlisted records. Catalog approval is not exposed through the Management API.

Get a shared dataset

GET/datasets/{id}
Required scope: datasets:read. Success status: 200.

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "id": "DATASET_ID",
    "project_id": "PROJECT_ID",
    "destination_id": "WAREHOUSE_ID",
    "name": "Global Cloud Reliability",
    "slug": "cloud-service-reliability",
    "description": "Public cloud service incidents and component health.",
    "status": "draft",
    "visibility": "unlisted",
    "catalog_status": "not_submitted",
    "source_name": "Public provider status APIs",
    "source_url": "https://example.com/status",
    "license_name": "Source terms",
    "license_url": "https://example.com/terms",
    "attribution": "Public provider status APIs",
    "warehouse": {
      "id": "WAREHOUSE_ID",
      "name": "Public Data · cloud-service-reliability",
      "type": "bigquery",
      "enabled": true
    },
    "models": [
      {
        "id": "MODEL_ID",
        "name": "Cloud incidents",
        "key": "cloud_service_incidents",
        "time_field": "observed_at",
        "enabled": true,
        "fields": []
      }
    ],
    "charts": [
      {
        "id": "ANALYTICS_API_ID",
        "key": "cloud_incidents_daily",
        "name": "Cloud incidents by day",
        "description": "Incident flow by day",
        "chart_type": "line",
        "updated_at": "2026-08-02T10:00:00Z"
      }
    ],
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Update a shared dataset

PUT/datasets/{id}
Required scope: datasets:write. Success status: 200.

Request JSON

{
  "project_id": "PROJECT_ID",
  "destination_id": "WAREHOUSE_ID",
  "name": "Global Cloud Reliability",
  "slug": "cloud-service-reliability",
  "description": "Public cloud service incidents and component health.",
  "status": "draft",
  "visibility": "unlisted",
  "schema_ids": [
    "MODEL_ID"
  ],
  "analytics_ids": [
    "ANALYTICS_API_ID"
  ],
  "source_name": "Public provider status APIs",
  "source_url": "https://example.com/status",
  "license_name": "Source terms",
  "license_url": "https://example.com/terms",
  "attribution": "Public provider status APIs"
}

Accepted values

{
  "status": [
    "draft",
    "published",
    "disabled"
  ],
  "visibility": [
    "unlisted",
    "public"
  ]
}

Response JSON

{
  "error": false,
  "data": {
    "id": "DATASET_ID",
    "project_id": "PROJECT_ID",
    "destination_id": "WAREHOUSE_ID",
    "name": "Global Cloud Reliability",
    "slug": "cloud-service-reliability",
    "description": "Public cloud service incidents and component health.",
    "status": "draft",
    "visibility": "unlisted",
    "catalog_status": "not_submitted",
    "source_name": "Public provider status APIs",
    "source_url": "https://example.com/status",
    "license_name": "Source terms",
    "license_url": "https://example.com/terms",
    "attribution": "Public provider status APIs",
    "warehouse": {
      "id": "WAREHOUSE_ID",
      "name": "Public Data · cloud-service-reliability",
      "type": "bigquery",
      "enabled": true
    },
    "models": [
      {
        "id": "MODEL_ID",
        "name": "Cloud incidents",
        "key": "cloud_service_incidents",
        "time_field": "observed_at",
        "enabled": true,
        "fields": []
      }
    ],
    "charts": [
      {
        "id": "ANALYTICS_API_ID",
        "key": "cloud_incidents_daily",
        "name": "Cloud incidents by day",
        "description": "Incident flow by day",
        "chart_type": "line",
        "updated_at": "2026-08-02T10:00:00Z"
      }
    ],
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Archive a shared dataset

DELETE/datasets/{id}
Required scope: datasets:write. Success status: 200.

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "archived": true
  }
}

Security resources

List Client CAs

GET/client-cas
Required scope: security:read. Success status: 200.

Query parameters

{
  "project_id": "PROJECT_ID"
}

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": [
    {
      "id": "CLIENT_CA_ID",
      "project_id": "PROJECT_ID",
      "name": "Production client CA",
      "subject": "CN=Production Client CA",
      "issuer": "CN=Production Client CA",
      "serial_number": "1234567890",
      "fingerprint_sha256": "SHA256_FINGERPRINT",
      "not_before": "2026-08-01T00:00:00Z",
      "not_after": "2027-08-01T00:00:00Z",
      "enabled": true,
      "workspace_shared": false,
      "created_at": "2026-08-02T10:00:00Z",
      "updated_at": "2026-08-02T10:00:00Z"
    }
  ]
}

Create a Client CA

POST/client-cas
Required scope: security:write. Success status: 201.

Request JSON

{
  "project_id": "PROJECT_ID",
  "name": "Production client CA",
  "workspace_shared": false,
  "certificate_pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
}

Accepted values

{
  "workspace_shared": [
    false,
    true
  ],
  "certificate_pem": [
    "PEM-encoded public CA certificate; never a private key"
  ]
}

Response JSON

{
  "error": false,
  "data": {
    "id": "CLIENT_CA_ID",
    "project_id": "PROJECT_ID",
    "name": "Production client CA",
    "subject": "CN=Production Client CA",
    "issuer": "CN=Production Client CA",
    "serial_number": "1234567890",
    "fingerprint_sha256": "SHA256_FINGERPRINT",
    "not_before": "2026-08-01T00:00:00Z",
    "not_after": "2027-08-01T00:00:00Z",
    "enabled": true,
    "workspace_shared": false,
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

workspace_shared: true requires workspace owner/admin access.

Get a Client CA

GET/client-cas/{id}
Required scope: security:read. Success status: 200.

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "id": "CLIENT_CA_ID",
    "project_id": "PROJECT_ID",
    "name": "Production client CA",
    "subject": "CN=Production Client CA",
    "issuer": "CN=Production Client CA",
    "serial_number": "1234567890",
    "fingerprint_sha256": "SHA256_FINGERPRINT",
    "not_before": "2026-08-01T00:00:00Z",
    "not_after": "2027-08-01T00:00:00Z",
    "enabled": true,
    "workspace_shared": false,
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Delete a Client CA

DELETE/client-cas/{id}
Required scope: security:write. Success status: 200.

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "deleted": true
  }
}

Alerts, Incidents, and Notification Channels

List Alerts

GET/alerts
Required scope: alerts:read. Success status: 200.

Query parameters

{
  "project_id": "PROJECT_ID",
  "trigger_type": "event",
  "enabled": true
}

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "items": [
      {
        "id": "ALERT_ID",
        "project_id": "PROJECT_ID",
        "name": "Repeated failed login",
        "description": "Ten failures from one source IP",
        "enabled": true,
        "severity": "critical",
        "trigger_type": "event",
        "schema_id": "MODEL_ID",
        "conditions": {
          "combinator": "and",
          "conditions": [
            {
              "field": "outcome",
              "operator": "equals",
              "value": "failed"
            }
          ]
        },
        "group_by": [
          "source_ip"
        ],
        "selected_fields": [
          "source_ip",
          "user_id"
        ],
        "trigger_mode": "threshold",
        "threshold": 10,
        "window_seconds": 300,
        "cooldown_seconds": 900,
        "absence_seconds": 0,
        "channel_ids": [
          "CHANNEL_ID"
        ],
        "evaluation_interval_seconds": 300,
        "consecutive_evaluations": 1,
        "created_at": "2026-08-02T10:00:00Z",
        "updated_at": "2026-08-02T10:00:00Z"
      }
    ],
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}

Create an Alert

POST/alerts
Required scope: alerts:write. Success status: 201.

Request JSON

{
  "id": "ALERT_ID",
  "project_id": "PROJECT_ID",
  "name": "Repeated failed login",
  "description": "Ten failures from one source IP",
  "enabled": true,
  "severity": "critical",
  "trigger_type": "event",
  "schema_id": "MODEL_ID",
  "conditions": {
    "combinator": "and",
    "conditions": [
      {
        "field": "outcome",
        "operator": "equals",
        "value": "failed"
      }
    ]
  },
  "group_by": [
    "source_ip"
  ],
  "selected_fields": [
    "source_ip",
    "user_id"
  ],
  "trigger_mode": "threshold",
  "threshold": 10,
  "window_seconds": 300,
  "cooldown_seconds": 900,
  "absence_seconds": 0,
  "channel_ids": [
    "CHANNEL_ID"
  ],
  "evaluation_interval_seconds": 300,
  "consecutive_evaluations": 1,
  "created_at": "2026-08-02T10:00:00Z",
  "updated_at": "2026-08-02T10:00:00Z"
}

Response JSON

{
  "error": false,
  "data": {
    "id": "ALERT_ID",
    "project_id": "PROJECT_ID",
    "name": "Repeated failed login",
    "description": "Ten failures from one source IP",
    "enabled": true,
    "severity": "critical",
    "trigger_type": "event",
    "schema_id": "MODEL_ID",
    "conditions": {
      "combinator": "and",
      "conditions": [
        {
          "field": "outcome",
          "operator": "equals",
          "value": "failed"
        }
      ]
    },
    "group_by": [
      "source_ip"
    ],
    "selected_fields": [
      "source_ip",
      "user_id"
    ],
    "trigger_mode": "threshold",
    "threshold": 10,
    "window_seconds": 300,
    "cooldown_seconds": 900,
    "absence_seconds": 0,
    "channel_ids": [
      "CHANNEL_ID"
    ],
    "evaluation_interval_seconds": 300,
    "consecutive_evaluations": 1,
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Get an Alert

GET/alerts/{id}
Required scope: alerts:read. Success status: 200.

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "id": "ALERT_ID",
    "project_id": "PROJECT_ID",
    "name": "Repeated failed login",
    "description": "Ten failures from one source IP",
    "enabled": true,
    "severity": "critical",
    "trigger_type": "event",
    "schema_id": "MODEL_ID",
    "conditions": {
      "combinator": "and",
      "conditions": [
        {
          "field": "outcome",
          "operator": "equals",
          "value": "failed"
        }
      ]
    },
    "group_by": [
      "source_ip"
    ],
    "selected_fields": [
      "source_ip",
      "user_id"
    ],
    "trigger_mode": "threshold",
    "threshold": 10,
    "window_seconds": 300,
    "cooldown_seconds": 900,
    "absence_seconds": 0,
    "channel_ids": [
      "CHANNEL_ID"
    ],
    "evaluation_interval_seconds": 300,
    "consecutive_evaluations": 1,
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Update an Alert

PUT/alerts/{id}
Required scope: alerts:write. Success status: 200.

Request JSON

{
  "id": "ALERT_ID",
  "project_id": "PROJECT_ID",
  "name": "Repeated failed login",
  "description": "Ten failures from one source IP",
  "enabled": true,
  "severity": "critical",
  "trigger_type": "event",
  "schema_id": "MODEL_ID",
  "conditions": {
    "combinator": "and",
    "conditions": [
      {
        "field": "outcome",
        "operator": "equals",
        "value": "failed"
      }
    ]
  },
  "group_by": [
    "source_ip"
  ],
  "selected_fields": [
    "source_ip",
    "user_id"
  ],
  "trigger_mode": "threshold",
  "threshold": 10,
  "window_seconds": 300,
  "cooldown_seconds": 900,
  "absence_seconds": 0,
  "channel_ids": [
    "CHANNEL_ID"
  ],
  "evaluation_interval_seconds": 300,
  "consecutive_evaluations": 1,
  "created_at": "2026-08-02T10:00:00Z",
  "updated_at": "2026-08-02T10:00:00Z"
}

Response JSON

{
  "error": false,
  "data": {
    "id": "ALERT_ID",
    "project_id": "PROJECT_ID",
    "name": "Repeated failed login",
    "description": "Ten failures from one source IP",
    "enabled": true,
    "severity": "critical",
    "trigger_type": "event",
    "schema_id": "MODEL_ID",
    "conditions": {
      "combinator": "and",
      "conditions": [
        {
          "field": "outcome",
          "operator": "equals",
          "value": "failed"
        }
      ]
    },
    "group_by": [
      "source_ip"
    ],
    "selected_fields": [
      "source_ip",
      "user_id"
    ],
    "trigger_mode": "threshold",
    "threshold": 10,
    "window_seconds": 300,
    "cooldown_seconds": 900,
    "absence_seconds": 0,
    "channel_ids": [
      "CHANNEL_ID"
    ],
    "evaluation_interval_seconds": 300,
    "consecutive_evaluations": 1,
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Archive an Alert

DELETE/alerts/{id}
Required scope: alerts:write. Success status: 200.

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "deleted": true
  }
}

Archives and disables the rule while retaining Incident and audit history.

Enable an Alert

POST/alerts/{id}/enable
Required scope: alerts:write. Success status: 200.

Request JSON

{}

Response JSON

{
  "error": false,
  "data": {
    "enabled": true
  }
}

Disable an Alert

POST/alerts/{id}/disable
Required scope: alerts:write. Success status: 200.

Request JSON

{}

Response JSON

{
  "error": false,
  "data": {
    "enabled": false
  }
}

Simulate an Event Alert

POST/alerts/{id}/simulate
Required scope: alerts:read. Success status: 200.

Request JSON

{
  "event": {
    "outcome": "failed",
    "source_ip": "203.0.113.10"
  }
}

Response JSON

{
  "error": false,
  "data": {
    "matched": true,
    "conditions": [
      {
        "field": "outcome",
        "operator": "equals",
        "matched": true,
        "reason": "values are equal"
      }
    ],
    "group_context": {
      "source_ip": "203.0.113.10"
    },
    "selected_fields": {
      "source_ip": "203.0.113.10"
    }
  }
}

List Notification Channels

GET/notification-channels
Required scope: alerts:read. Success status: 200.

Query parameters

{
  "project_id": "PROJECT_ID"
}

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "items": [
      {
        "id": "CHANNEL_ID",
        "project_id": "PROJECT_ID",
        "name": "SOC webhook",
        "type": "webhook",
        "enabled": true,
        "secret_configured": true,
        "config": {
          "url_configured": true
        },
        "created_at": "2026-08-02T10:00:00Z",
        "updated_at": "2026-08-02T10:00:00Z"
      }
    ],
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}

Create a Notification Channel

POST/notification-channels
Required scope: alerts:write. Success status: 201.

Request JSON

{
  "project_id": "PROJECT_ID",
  "name": "SOC webhook",
  "type": "webhook",
  "enabled": true,
  "config": {},
  "secret": {
    "url": "https://alerts.example.com/reportplane",
    "hmac_secret": "WRITE_ONLY_SECRET_AT_LEAST_32_CHARS"
  }
}

Response JSON

{
  "error": false,
  "data": {
    "id": "CHANNEL_ID",
    "project_id": "PROJECT_ID",
    "name": "SOC webhook",
    "type": "webhook",
    "enabled": true,
    "secret_configured": true,
    "config": {
      "url_configured": true
    },
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Endpoint and secret values are encrypted and never returned.

Get a Notification Channel

GET/notification-channels/{id}
Required scope: alerts:read. Success status: 200.

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "id": "CHANNEL_ID",
    "project_id": "PROJECT_ID",
    "name": "SOC webhook",
    "type": "webhook",
    "enabled": true,
    "secret_configured": true,
    "config": {
      "url_configured": true
    },
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Update a Notification Channel

PUT/notification-channels/{id}
Required scope: alerts:write. Success status: 200.

Request JSON

{
  "name": "SOC webhook",
  "type": "webhook",
  "enabled": true,
  "config": {},
  "secret": {
    "url": "https://alerts.example.com/reportplane",
    "hmac_secret": "ROTATED_WRITE_ONLY_SECRET_32_CHARS"
  }
}

Response JSON

{
  "error": false,
  "data": {
    "id": "CHANNEL_ID",
    "project_id": "PROJECT_ID",
    "name": "SOC webhook",
    "type": "webhook",
    "enabled": true,
    "secret_configured": true,
    "config": {
      "url_configured": true
    },
    "created_at": "2026-08-02T10:00:00Z",
    "updated_at": "2026-08-02T10:00:00Z"
  }
}

Enable a Notification Channel

POST/notification-channels/{id}/enable
Required scope: alerts:write. Success status: 200.

Request JSON

{}

Response JSON

{
  "error": false,
  "data": {
    "enabled": true
  }
}

Disable a Notification Channel

POST/notification-channels/{id}/disable
Required scope: alerts:write. Success status: 200.

Request JSON

{}

Response JSON

{
  "error": false,
  "data": {
    "enabled": false
  }
}

Send a test notification

POST/notification-channels/{id}/test
Required scope: alerts:write. Success status: 202.

Request JSON

{}

Response JSON

{
  "error": false,
  "data": {
    "id": "DELIVERY_ID",
    "project_id": "PROJECT_ID",
    "incident_id": "INCIDENT_ID",
    "channel_id": "CHANNEL_ID",
    "status": "delivered",
    "attempt_count": 1,
    "next_attempt_at": "2026-08-02T10:00:00Z",
    "delivered_at": "2026-08-02T10:00:00Z",
    "last_error": ""
  }
}

List Alert Incidents

GET/alert-incidents
Required scope: alerts:read. Success status: 200.

Query parameters

{
  "project_id": "PROJECT_ID",
  "status": "open"
}

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "items": [
      {
        "id": "INCIDENT_ID",
        "project_id": "PROJECT_ID",
        "alert_rule_id": "ALERT_ID",
        "status": "open",
        "severity": "critical",
        "group_key": "GROUP_HASH",
        "group_context": {
          "source_ip": "203.0.113.10"
        },
        "first_seen_at": "2026-08-02T10:00:00Z",
        "last_seen_at": "2026-08-02T10:00:00Z",
        "occurrence_count": 10
      }
    ],
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}

Get an Alert Incident

GET/alert-incidents/{id}
Required scope: alerts:read. Success status: 200.

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "incident": {
      "id": "INCIDENT_ID",
      "project_id": "PROJECT_ID",
      "alert_rule_id": "ALERT_ID",
      "status": "open",
      "severity": "critical",
      "group_key": "GROUP_HASH",
      "group_context": {
        "source_ip": "203.0.113.10"
      },
      "first_seen_at": "2026-08-02T10:00:00Z",
      "last_seen_at": "2026-08-02T10:00:00Z",
      "occurrence_count": 10
    },
    "occurrences": [],
    "deliveries": [
      {
        "id": "DELIVERY_ID",
        "project_id": "PROJECT_ID",
        "incident_id": "INCIDENT_ID",
        "channel_id": "CHANNEL_ID",
        "status": "delivered",
        "attempt_count": 1,
        "next_attempt_at": "2026-08-02T10:00:00Z",
        "delivered_at": "2026-08-02T10:00:00Z",
        "last_error": ""
      }
    ]
  }
}

Acknowledge an Incident

POST/alert-incidents/{id}/acknowledge
Required scope: alerts:write. Success status: 200.

Request JSON

{}

Response JSON

{
  "error": false,
  "data": {
    "status": "acknowledged"
  }
}

Resolve an Incident

POST/alert-incidents/{id}/resolve
Required scope: alerts:write. Success status: 200.

Request JSON

{}

Response JSON

{
  "error": false,
  "data": {
    "status": "resolved"
  }
}

Inspect an Alert delivery

GET/alert-deliveries/{id}
Required scope: alerts:read. Success status: 200.

Request JSON

No request body.

Response JSON

{
  "error": false,
  "data": {
    "id": "DELIVERY_ID",
    "project_id": "PROJECT_ID",
    "incident_id": "INCIDENT_ID",
    "channel_id": "CHANNEL_ID",
    "status": "delivered",
    "attempt_count": 1,
    "next_attempt_at": "2026-08-02T10:00:00Z",
    "delivered_at": "2026-08-02T10:00:00Z",
    "last_error": ""
  }
}

Retry an Alert delivery

POST/alert-deliveries/{id}/retry
Required scope: alerts:write. Success status: 202.

Request JSON

{}

Response JSON

{
  "error": false,
  "data": {
    "queued": true
  }
}

Requeues an authorized failed or dead-letter delivery with a fresh bounded attempt cycle.

Was this page helpful?Send feedback