openapi: 3.1.0 info: title: HoneyHive Control Plane API description: | Manage HoneyHive control-plane resources: organizations, workspaces, projects and alerts, and read org usage. Authentication requires a fine-grained control-plane API key (values start with `hh_fgcp_`), sent as `Authorization: Bearer `. Project API keys used with the Data Plane API will not work here. Create a key in the HoneyHive app under an organization's or workspace's **Settings → API Keys**, or see [Authorization](https://docs.honeyhive.ai/v2/control-plane-sdk-reference/typescript#authorization) for details. license: name: MIT url: https://opensource.org/licenses/MIT version: 1.17.0 servers: - url: https://api.cp.us.honeyhive.ai tags: - name: Alerts description: | Define and manage alerts. Alerts evaluate event metrics on a schedule and trigger notifications when configured thresholds are crossed. - name: Orgs description: | Read an organization's display name and the email domains whose users join it automatically when they sign in, and update its display name. - name: Projects description: | Create and manage projects within a workspace. A project is the container for the events, datasets, evaluations, and alerts logged against it. - name: Usage description: | Read an organization's usage: events and computed metrics per calendar month, and current user, workspace and project counts. - name: Virtual Dataplanes description: | Create and manage virtual data planes. A virtual data plane is a logical tenant boundary inside an organization, hosted on a physical cluster; several virtual data planes commonly share one cluster. Workspaces live inside a virtual data plane. - name: Workspaces description: | Read and manage workspaces. A workspace groups the projects belonging to one team or environment, and owns the API keys and AI provider secrets its projects share. paths: /v1/projects/{project_id}/alerts: get: tags: - Alerts operationId: listAlerts security: - ControlPlaneApiKey: [] x-cli-name: list x-ts-sdk-name: list summary: List alerts description: | List the alerts in a project. The project is identified by the `project_id` path parameter alone; the `x-hh-project-id` header does not participate. Supports offset pagination, an optional status filter, and sorting (defaults to most recently created first). parameters: - in: path name: project_id required: true schema: type: string description: The unique identifier of the project whose alerts are listed - in: query name: page required: false schema: type: integer minimum: 1 default: 1 description: 1-indexed page number - in: query name: limit required: false schema: type: integer minimum: 1 maximum: 100 default: 20 description: Number of alerts to return per page - in: query name: status required: false schema: type: string enum: - ACTIVE - TRIGGERED - PAUSED - RESOLVED description: Only return alerts in this status - in: query name: sort_by required: false schema: type: string enum: - created_at - updated_at - name - status - frequency - last_triggered default: created_at description: Field to sort results by - in: query name: sort_order required: false schema: type: string enum: - asc - desc default: desc description: Sort order responses: '200': description: Alerts retrieved successfully content: application/json: schema: $ref: '#/components/schemas/GetAlertsResponse' '400': description: Invalid pagination or filter parameters post: tags: - Alerts operationId: createAlert security: - ControlPlaneApiKey: [] x-cli-name: create x-ts-sdk-name: create summary: Create an alert description: | Create an alert in a project. The project is identified by the `project_id` path parameter alone; the `x-hh-project-id` header does not participate. The alert's `filters` and `projections` (metrics) are mapped against the project's logged-event schema; if no schema data matches them — e.g. no events have been logged to the project yet — the request fails with a 400. parameters: - in: path name: project_id required: true schema: type: string description: The unique identifier of the project the alert is created in requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PostAlertRequest' responses: '200': description: Alert created successfully content: application/json: schema: $ref: '#/components/schemas/CreateAlertResponse' '400': description: Invalid request body, or no schema data matches the selected filters/metrics '404': description: Project not found /v1/projects/{project_id}/alerts/{alert_id}: get: tags: - Alerts operationId: getAlert security: - ControlPlaneApiKey: [] x-cli-name: get x-ts-sdk-name: get summary: Get an alert description: | Retrieve a single alert by id, including its thresholds, triggers, and notification configuration. The alert's project is identified by the `project_id` path parameter alone; the `x-hh-project-id` header does not participate. parameters: - in: path name: project_id required: true schema: type: string description: The unique identifier of the project the alert belongs to - in: path name: alert_id required: true schema: type: string description: The unique identifier of the alert to retrieve responses: '200': description: Alert retrieved successfully content: application/json: schema: $ref: '#/components/schemas/GetAlertResponse' '404': description: Alert not found /v1/virtual_dataplanes/{virtual_dataplane_id}/workspaces: post: tags: - Workspaces operationId: createWorkspace security: - ControlPlaneApiKey: [] x-cli-name: create x-ts-sdk-name: create summary: Create a workspace description: | Create a workspace in a virtual data plane. The parent virtual data plane is identified by the `virtual_dataplane_id` path parameter alone; the `x-hh-dataplane-id` header does not participate. Your organization's virtual data plane ids are listed on the API keys page of your organization settings in the HoneyHive app. Most organizations have exactly one. The new workspace contains no projects. Create one with `POST /v1/workspaces/{workspace_id}/projects` if you need it, because a workspace with no projects has nowhere to log events. The optional `workspace_creator` field names the user (by email) who receives the workspace-creator membership on the new workspace. The named user must already be a member of the virtual data plane. When omitted, the workspace is created without any membership. The field is only accepted on API-key-initiated requests. User-initiated creation always makes the calling user the creator, so sending the field returns a 400. The roles that membership carries come from your organization's role configuration. An organization that grants no role on workspace creation is a supported case: the request still succeeds and the named user receives no access. A 200 response is not by itself confirmation that the named user was granted anything. A `workspace_creator` who is already signed in does not see the new workspace immediately. A session captures its scope tree and permission grants when it is created, so a membership granted afterwards is not reflected in it. Creating the workspace marks that user's sessions for refresh, and the refresh takes effect on their next request to the control plane, so an idle browser tab may need a page reload. parameters: - in: path name: virtual_dataplane_id required: true schema: type: string description: The unique identifier of the virtual data plane the workspace is created in requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PostWorkspaceRequest' responses: '200': description: Workspace created successfully content: application/json: schema: $ref: '#/components/schemas/CreateWorkspaceResponse' '400': description: Invalid request body, or an unknown/ineligible `workspace_creator` '404': description: Virtual data plane not found '409': description: The `slug` is already taken by another scope /v1/workspaces/{workspace_id}/projects: post: tags: - Projects operationId: createProject security: - ControlPlaneApiKey: [] x-cli-name: create x-ts-sdk-name: create summary: Create a project description: | Create a project in a workspace. The parent workspace is identified by the `workspace_id` path parameter alone; the `x-hh-workspace-id` header does not participate. A workspace's id is listed on the API keys page of its workspace settings in the HoneyHive app. The optional `project_creator` field names the user (by email) who receives the project-creator membership on the new project. The named user must already be a member of the workspace. When omitted, the project is created without any membership. The field is only accepted on API-key-initiated requests. User-initiated creation always makes the calling user the creator, so sending the field returns a 400. The roles that membership carries come from your organization's role configuration. An organization that grants no role on project creation is a supported case: the request still succeeds and the named user receives no access. A 200 response is not by itself confirmation that the named user was granted anything. A `project_creator` who is already signed in does not see the new project immediately. A session captures its scope tree and permission grants when it is created, so a membership granted afterwards is not reflected in it. Creating the project marks that user's sessions for refresh, and the refresh takes effect on their next request to the control plane, so an idle browser tab may need a page reload. parameters: - in: path name: workspace_id required: true schema: type: string description: The unique identifier of the workspace the project is created in requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PostProjectRequest' responses: '200': description: Project created successfully content: application/json: schema: $ref: '#/components/schemas/CreateProjectResponse' '400': description: Invalid request body, or an unknown/ineligible `project_creator` '404': description: Workspace not found /v1/projects/{project_id}: get: tags: - Projects operationId: getProject security: - ControlPlaneApiKey: [] x-cli-name: get x-ts-sdk-name: get summary: Get a project description: | Retrieve a single project by id. The project is identified by the `project_id` path parameter alone; the `x-hh-project-id` header does not participate. parameters: - in: path name: project_id required: true schema: type: string description: The unique identifier of the project to retrieve responses: '200': description: Project retrieved successfully content: application/json: schema: $ref: '#/components/schemas/GetProjectResponse' '404': description: Project not found put: tags: - Projects operationId: updateProject security: - ControlPlaneApiKey: [] x-cli-name: update x-ts-sdk-name: update summary: Update a project description: | Update a project's display name and/or description. The project is identified by the `project_id` path parameter alone; the `x-hh-project-id` header does not participate. Only fields included in the request body are modified. parameters: - in: path name: project_id required: true schema: type: string description: The unique identifier of the project to update requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PutProjectRequest' responses: '200': description: Project updated successfully content: application/json: schema: $ref: '#/components/schemas/UpdateProjectResponse' '400': description: Invalid request body '404': description: Project not found delete: tags: - Projects operationId: deleteProject security: - ControlPlaneApiKey: [] x-cli-name: delete x-ts-sdk-name: delete summary: Delete a project description: | Delete a project. The project is soft-deleted (archived) and no longer appears in reads; the response returns the archived project. The project is identified by the `project_id` path parameter alone; the `x-hh-project-id` header does not participate. parameters: - in: path name: project_id required: true schema: type: string description: The unique identifier of the project to delete responses: '200': description: Project deleted successfully content: application/json: schema: $ref: '#/components/schemas/DeleteProjectResponse' '404': description: Project not found /v1/workspaces/{workspace_id}: get: tags: - Workspaces operationId: getWorkspace security: - ControlPlaneApiKey: [] x-cli-name: get x-ts-sdk-name: get summary: Get a workspace description: | Retrieve a single workspace by id. The workspace is identified by the `workspace_id` path parameter alone; the `x-hh-workspace-id` header does not participate. The returned `name` is the workspace's display name. The globally unique slug the workspace was assigned at creation is an internal detail and is not part of this contract. parameters: - in: path name: workspace_id required: true schema: type: string description: The unique identifier of the workspace to retrieve responses: '200': description: Workspace retrieved successfully content: application/json: schema: $ref: '#/components/schemas/GetWorkspaceResponse' '404': description: Workspace not found put: tags: - Workspaces operationId: updateWorkspace security: - ControlPlaneApiKey: [] x-cli-name: update x-ts-sdk-name: update summary: Update a workspace description: | Update a workspace's display name and/or description. The workspace is identified by the `workspace_id` path parameter alone; the `x-hh-workspace-id` header does not participate. Only fields included in the request body are modified. The workspace's internal slug is not part of this contract and cannot be changed here. parameters: - in: path name: workspace_id required: true schema: type: string description: The unique identifier of the workspace to update requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PutWorkspaceRequest' responses: '200': description: Workspace updated successfully content: application/json: schema: $ref: '#/components/schemas/UpdateWorkspaceResponse' '400': description: Invalid request body '404': description: Workspace not found delete: tags: - Workspaces operationId: deleteWorkspace security: - ControlPlaneApiKey: [] x-cli-name: delete x-ts-sdk-name: delete summary: Delete a workspace description: | Delete a workspace. The workspace is soft-deleted (archived) and no longer appears in reads; the response returns the archived workspace. The workspace is identified by the `workspace_id` path parameter alone; the `x-hh-workspace-id` header does not participate. **Deleting a workspace also archives every project inside it**, so the events, datasets, and evaluations in those projects are no longer reachable. Because that reaches well beyond the resource named in the URL, a workspace that still has active projects is rejected with a 409 unless the request sets `dangerously_delete_child_scopes=true`. Projects that were already archived do not count, so a workspace emptied one project at a time deletes without the flag. The response describes only the workspace. It does not enumerate the projects archived alongside it, so read them first if you need that list. parameters: - in: path name: workspace_id required: true schema: type: string description: The unique identifier of the workspace to delete - in: query name: dangerously_delete_child_scopes required: false schema: type: boolean default: false description: | Archive the workspace even when it still has active projects, archiving those projects too. Without it, such a request fails with a 409 and no changes are made. responses: '200': description: Workspace deleted successfully content: application/json: schema: $ref: '#/components/schemas/DeleteWorkspaceResponse' '400': description: '`dangerously_delete_child_scopes` is not `true` or `false`' '404': description: Workspace not found '409': description: The workspace still has active projects and `dangerously_delete_child_scopes` was not set /v1/orgs/{org_id}: get: tags: - Orgs operationId: getOrg security: - ControlPlaneApiKey: [] x-cli-name: get x-ts-sdk-name: get summary: Get an organization description: | Retrieve an organization's display name and email domains. The organization is identified by the `org_id` path parameter alone; the `x-hh-org-id` header does not participate. Your organization's id is listed on the API keys page of your organization settings in the HoneyHive app. parameters: - in: path name: org_id required: true schema: type: string description: The unique identifier of the organization to retrieve responses: '200': description: Organization retrieved successfully content: application/json: schema: $ref: '#/components/schemas/GetOrgResponse' '404': description: Organization not found patch: tags: - Orgs operationId: updateOrg security: - ControlPlaneApiKey: [] x-cli-name: update x-ts-sdk-name: update summary: Update an organization description: | Update an organization's display name. The organization is identified by the `org_id` path parameter alone; the `x-hh-org-id` header does not participate. The organization's email domains cannot be changed through the API. Set them in the organization settings of the HoneyHive app. parameters: - in: path name: org_id required: true schema: type: string description: The unique identifier of the organization to update requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PatchOrgRequest' responses: '200': description: Organization updated successfully content: application/json: schema: $ref: '#/components/schemas/UpdateOrgResponse' '400': description: Invalid request body '404': description: Organization not found /v1/orgs/{org_id}/virtual_dataplanes: post: tags: - Virtual Dataplanes operationId: createVirtualDataplane security: - ControlPlaneApiKey: [] x-cli-name: create x-ts-sdk-name: create summary: Create a virtual data plane description: | Create a virtual data plane in an organization. The parent organization is identified by the `org_id` path parameter alone; the `x-hh-org-id` header does not participate. Your organization's id is listed on the API keys page of your organization settings in the HoneyHive app. A virtual data plane is a logical tenant boundary hosted on a physical cluster, and several of them commonly share one cluster. Workspaces are created inside it. `cluster_id` is optional, and omitting it is the common case: the new virtual data plane is placed on the same cluster as the organization's existing ones. Two situations require it explicitly, and both return a 400 that says so rather than guessing: an organization whose existing virtual data planes span more than one cluster, and an organization that has none yet. Every response includes `cluster_id`, so reading an existing virtual data plane tells you which value to send. A cluster admits an organization only if your control plane administrator configured it to, so a `cluster_id` you can read from a sibling virtual data plane is not necessarily one you may place a new virtual data plane on. A cluster that does not admit this organization returns a 404. When this endpoint inferred the cluster, send an explicit `cluster_id` to place the virtual data plane on another cluster. Deployments differ in who places virtual data planes. Where HoneyHive assigns them to organizations automatically, this endpoint returns a 404 for every request and the placement is not yours to make. Deployments whose administrators own the scope tree are the ones this endpoint serves. The optional `dataplane_creator` field names the user (by email) who receives the dataplane-creator membership on the new virtual data plane. The named user must already be a member of the organization. When omitted, it is created without any membership. The field is only accepted on API-key-initiated requests; user-initiated creation always makes the calling user the creator, so sending the field returns a 400. The roles that membership carries come from your organization's role configuration. An organization that grants no role on dataplane creation is a supported case: the request still succeeds and the named user receives no access. A 200 response is not by itself confirmation that the named user was granted anything. A `dataplane_creator` who is already signed in does not see the new virtual data plane immediately. A session captures its scope tree and permission grants when it is created, so a membership granted afterwards is not reflected in it; the refresh takes effect on their next request to the control plane. parameters: - in: path name: org_id required: true schema: type: string description: The unique identifier of the organization the virtual data plane is created in requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PostVirtualDataplaneRequest' responses: '200': description: Virtual data plane created successfully content: application/json: schema: $ref: '#/components/schemas/CreateVirtualDataplaneResponse' '400': description: Invalid request body, an unknown or ineligible `dataplane_creator`, `cluster_id` omitted when it could not be inferred, or the named cluster is disabled '404': description: Organization or cluster not found, or the caller may not create a virtual data plane here. The response does not say which. '409': description: The `slug` is already taken by another scope /v1/orgs/{org_id}/usage: get: tags: - Usage operationId: getUsage security: - ControlPlaneApiKey: [] x-cli-name: get x-ts-sdk-name: get summary: Get usage for a date range description: | Return an organization's usage for `[start_date, end_date)`, in one bucket per calendar month, clipped to the range and ending at the current month. The organization is identified by the `org_id` path parameter alone; the `x-hh-org-id` header does not participate. An event counts in the month that contains its `start_time`, which the client sets when it logs the event, so usage for a past month can still grow. `metrics_computed_count` is the number of `metrics.*` keys on those events. Results are always split by `event_type`; pass `group_by` to also split them by workspace or by project. Every row is returned in one response; there is no pagination. Quarter- and year-to-date totals are for the caller to sum across ranges. parameters: - in: path name: org_id required: true schema: type: string description: The unique identifier of the organization - in: query name: start_date required: true schema: type: string format: date description: Inclusive start, `YYYY-MM-DD` (UTC), no later than today - in: query name: end_date required: true schema: type: string format: date description: Exclusive end, `YYYY-MM-DD` (UTC), 1 to 92 days after `start_date` - in: query name: group_by required: false schema: type: string enum: - workspace_id - project_id description: | Split results by workspace, or by project (each project row also carries its workspace) responses: '200': description: Usage computed successfully content: application/json: schema: $ref: '#/components/schemas/GetUsageResponse' '400': description: Missing or malformed dates, a range outside 1 to 92 days, a `start_date` after today, an unknown `group_by`, or an unknown query parameter '404': description: Organization not found, or the caller may not read its usage. The response does not say which. '422': description: The usage query exceeded its time budget (`errorCode` `query_timeout`) or its memory budget (`errorCode` `query_too_large`). Request a shorter range, or omit `group_by`. /v1/orgs/{org_id}/usage/current: get: tags: - Usage operationId: getUsageCurrent security: - ControlPlaneApiKey: [] x-cli-name: current x-ts-sdk-name: getCurrent summary: Get current usage counts description: | Return an organization's current counts, independent of any date range: members who completed onboarding, and non-archived workspaces and projects. The organization is identified by the `org_id` path parameter alone; the `x-hh-org-id` header does not participate. parameters: - in: path name: org_id required: true schema: type: string description: The unique identifier of the organization responses: '200': description: Counts read successfully content: application/json: schema: $ref: '#/components/schemas/GetUsageCurrentResponse' '404': description: Organization not found, or the caller may not read its usage. The response does not say which. /v1/virtual_dataplanes/{virtual_dataplane_id}: get: tags: - Virtual Dataplanes operationId: getVirtualDataplane security: - ControlPlaneApiKey: [] x-cli-name: get x-ts-sdk-name: get summary: Get a virtual data plane description: | Retrieve a single virtual data plane by id. It is identified by the `virtual_dataplane_id` path parameter alone; the `x-hh-dataplane-id` header does not participate. The returned `name` is the display name. The globally unique slug assigned at creation is an internal detail and is not part of this contract. `cluster_id` is the physical cluster hosting this virtual data plane, and it is the value to send when creating another one beside it. Reads work on every deployment, including those where HoneyHive assigns virtual data planes automatically and the write endpoints are unavailable. parameters: - in: path name: virtual_dataplane_id required: true schema: type: string description: The unique identifier of the virtual data plane to retrieve responses: '200': description: Virtual data plane retrieved successfully content: application/json: schema: $ref: '#/components/schemas/GetVirtualDataplaneResponse' '404': description: Virtual data plane not found put: tags: - Virtual Dataplanes operationId: updateVirtualDataplane security: - ControlPlaneApiKey: [] x-cli-name: update x-ts-sdk-name: update summary: Update a virtual data plane description: | Update a virtual data plane's display name. It is identified by the `virtual_dataplane_id` path parameter alone; the `x-hh-dataplane-id` header does not participate. `name` is the only field this endpoint changes. `cluster_id` is placement rather than description: the workspaces and projects inside a virtual data plane hold data on the cluster hosting it, so moving one is a migration and not an update. A request that omits `name`, or sends the current one, changes nothing. This endpoint is unavailable where HoneyHive assigns virtual data planes automatically, and returns a 404 there. parameters: - in: path name: virtual_dataplane_id required: true schema: type: string description: The unique identifier of the virtual data plane to update requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PutVirtualDataplaneRequest' responses: '200': description: Virtual data plane updated successfully content: application/json: schema: $ref: '#/components/schemas/UpdateVirtualDataplaneResponse' '400': description: Invalid request body '404': description: Virtual data plane not found, or the caller may not update it, or this deployment assigns virtual data planes automatically. The response does not say which. delete: tags: - Virtual Dataplanes operationId: deleteVirtualDataplane security: - ControlPlaneApiKey: [] x-cli-name: delete x-ts-sdk-name: delete summary: Delete a virtual data plane description: | Delete a virtual data plane. It is soft-deleted (archived) and no longer appears in reads; the response returns the archived virtual data plane. It is identified by the `virtual_dataplane_id` path parameter alone; the `x-hh-dataplane-id` header does not participate. **Deleting a virtual data plane also archives every workspace inside it and every project inside those workspaces**, so the events, datasets, and evaluations in them are no longer reachable. Because that reaches two levels below the resource named in the URL, a virtual data plane with active workspaces is rejected with a 409 unless the request sets `dangerously_delete_child_scopes=true`. Workspaces that were already archived do not count. The response describes only the virtual data plane. It does not enumerate what the cascade archived, so read that first if you need the list. This endpoint is unavailable where HoneyHive assigns virtual data planes automatically, and returns a 404 there. parameters: - in: path name: virtual_dataplane_id required: true schema: type: string description: The unique identifier of the virtual data plane to delete - in: query name: dangerously_delete_child_scopes required: false schema: type: boolean default: false description: | Archive the virtual data plane even when it still has active workspaces, archiving those workspaces and their projects too. Without it, such a request fails with a 409 and no changes are made. responses: '200': description: Virtual data plane deleted successfully content: application/json: schema: $ref: '#/components/schemas/DeleteVirtualDataplaneResponse' '400': description: '`dangerously_delete_child_scopes` is not `true` or `false`' '404': description: Virtual data plane not found, or the caller may not delete it, or this deployment assigns virtual data planes automatically. The response does not say which. '409': description: The virtual data plane still has active workspaces and `dangerously_delete_child_scopes` was not set components: securitySchemes: ControlPlaneApiKey: type: http scheme: bearer description: A fine-grained control-plane API key (values begin with `hh_fgcp_`). Project API keys used with the Data Plane API will not work here. Create one in the HoneyHive app under an organization's or workspace's **Settings → API Keys**. schemas: AlertItem: type: object properties: id: type: string name: type: string description: type: - string - 'null' status: type: string enum: - ACTIVE - TRIGGERED - PAUSED - RESOLVED frequency: type: string enum: - HOURLY - DAILY - WEEKLY - MONTHLY minimum_sample_size: type: integer alert_type: type: string enum: - DRIFT - AGGREGATE - PER_EVENT aggregation: type: string event_filters: type: array items: $ref: '#/components/schemas/AlertEventFilter' event_metrics: type: array items: $ref: '#/components/schemas/AlertEventMetric' thresholds: $ref: '#/components/schemas/AlertItemThresholds' last_run_at: anyOf: - type: string format: date-time - type: string - type: 'null' last_result: type: - object - 'null' properties: current_bucket_score: anyOf: - type: number - type: boolean previous_bucket_score: anyOf: - type: number - type: boolean last_triggered_baseline: anyOf: - type: number - type: boolean drift_percentage: type: number thresholds: $ref: '#/components/schemas/AlertItemLastResultThresholds' event_filters: type: array items: {} event_metrics: type: array items: {} aggregation: type: string additionalProperties: {} trigger_error: type: - string - 'null' is_active: type: boolean is_muted: type: boolean created_at: anyOf: - type: string format: date-time - type: string updated_at: anyOf: - type: string format: date-time - type: string - type: 'null' last_trigger_id: type: - string - 'null' scope_type: type: string scope_id: type: string created_by: type: - string - 'null' last_trigger: $ref: '#/components/schemas/AlertTrigger' triggers: type: array items: $ref: '#/components/schemas/AlertTrigger' notifications: type: array items: $ref: '#/components/schemas/AlertNotification' required: - id - name - status - frequency - minimum_sample_size - alert_type - aggregation - event_filters - event_metrics - thresholds - is_active - is_muted - created_at - scope_type - scope_id additionalProperties: false description: Alert object AlertEventFilter: type: object properties: filter: $ref: '#/components/schemas/SingleFilter' type: type: string enum: - float - numeric - boolean - string - 'null' required: - filter - type additionalProperties: false SingleFilter: type: object properties: field: type: string operator: type: string enum: - exists - not exists - is - is not - contains - not contains - greater than - less than - after - before value: anyOf: - type: string - type: number - type: boolean - type: 'null' type: type: string enum: - string - number - boolean - datetime required: - field - operator - value - type AlertEventMetric: type: object properties: projection: type: string description: Projected field or metric for this entry type: type: string enum: - float - numeric - boolean - string - 'null' required: - projection - type additionalProperties: false AlertTrigger: type: object properties: id: type: string alert_id: type: string result: $ref: '#/components/schemas/AlertTriggerResult' muted: type: boolean notification_sent: type: boolean triggered_time: anyOf: - type: string format: date-time - type: string resolved_time: anyOf: - type: string format: date-time - type: string - type: 'null' resolved_by: type: - string - 'null' created_at: anyOf: - type: string format: date-time - type: string updated_at: anyOf: - type: string format: date-time - type: string required: - id - alert_id - result - muted - notification_sent - triggered_time - resolved_time - resolved_by - created_at - updated_at additionalProperties: false AlertNotification: type: object properties: id: type: string alert_id: type: string stage: type: string enum: - CRITICAL - RESOLUTION channel: type: string enum: - EMAIL - SLACK - WEBHOOK scope: type: string enum: - ALL_PROJECT_MEMBERS - SPECIFIC_MEMBER membership_id: type: - string - 'null' metadata: type: - object - 'null' additionalProperties: {} last_sent_at: anyOf: - type: string format: date-time - type: string - type: 'null' created_at: anyOf: - type: string format: date-time - type: string membership: type: - object - 'null' properties: user: $ref: '#/components/schemas/AlertNotificationMembershipUser' required: - user additionalProperties: false required: - id - alert_id - stage - channel - scope - created_at additionalProperties: false PostAlertRequest: type: object properties: name: type: string minLength: 1 description: type: string frequency: type: string enum: - HOURLY - DAILY - WEEKLY - MONTHLY minimum_sample_size: type: integer default: 0 alert_type: type: string enum: - DRIFT - AGGREGATE - PER_EVENT default: AGGREGATE aggregation: type: string enum: - AVERAGE - COUNT - SUM - MIN - MAX - P90 - P95 - P99 - MEDIAN default: AVERAGE thresholds: $ref: '#/components/schemas/PostAlertRequestThresholds' filters: type: array items: $ref: '#/components/schemas/SingleFilter' projections: type: array items: type: string notification_details: $ref: '#/components/schemas/PostAlertRequestNotificationDetails' status: type: string enum: - ACTIVE - TRIGGERED - PAUSED - RESOLVED required: - name - frequency - thresholds - filters - projections - notification_details additionalProperties: false GetAlertResponse: type: object properties: success: type: boolean enum: - true data: $ref: '#/components/schemas/AlertItem' required: - success - data additionalProperties: false description: A single alert GetAlertsResponse: type: object properties: success: type: boolean enum: - true data: type: array items: $ref: '#/components/schemas/AlertItem' pagination: $ref: '#/components/schemas/Pagination' required: - success - data - pagination additionalProperties: false description: A paginated list of alerts Pagination: type: object properties: page: type: integer minimum: 1 limit: type: integer minimum: 1 total: type: integer minimum: 0 total_unfiltered: type: integer minimum: 0 total_pages: type: integer minimum: 0 has_next: type: boolean has_prev: type: boolean required: - page - limit - total - total_unfiltered - total_pages - has_next - has_prev CreateAlertResponse: type: object properties: success: type: boolean enum: - true data: $ref: '#/components/schemas/AlertItem' required: - success - data additionalProperties: false description: The created alert OrgItem: type: object properties: id: type: string name: type: string description: Organization display name email_domains: type: array items: type: string description: Email domains for automatic membership. A user who signs in through SSO or a social login with an email at one of these domains joins the organization. The API cannot change them. Set them in the organization settings of the HoneyHive app. created_at: anyOf: - type: string format: date-time - type: string updated_at: anyOf: - type: string format: date-time - type: string - type: 'null' required: - id - name - email_domains - created_at additionalProperties: false description: Organization object PatchOrgRequest: type: object properties: name: type: string maxLength: 200 description: Organization display name. Allowed characters are the letters A-Z and a-z (no accented letters), digits, space, underscore, hyphen, apostrophe and ampersand, and the name must not start with a space. additionalProperties: false description: Request body for updating an organization GetOrgResponse: type: object properties: success: type: boolean data: $ref: '#/components/schemas/OrgItem' required: - success - data additionalProperties: false description: A single organization UpdateOrgResponse: type: object properties: success: type: boolean data: $ref: '#/components/schemas/OrgItem' required: - success - data additionalProperties: false description: The updated organization ProjectItem: type: object properties: id: type: string name: type: string description: Project display name description: type: string description: Project description created_at: anyOf: - type: string format: date-time - type: string updated_at: anyOf: - type: string format: date-time - type: string - type: 'null' required: - id - name - description - created_at additionalProperties: false description: Project object PostProjectRequest: type: object properties: name: type: string minLength: 1 description: Project display name description: type: string description: Project description project_creator: type: string format: email description: Email of the user to grant the project-creator membership to (API key actors only). A signed-in user does not see the new project until their session refreshes, which happens on their next request to the control plane. required: - name additionalProperties: false description: Request body for creating a project PutProjectRequest: type: object properties: name: type: string minLength: 1 description: Project display name description: type: string description: Project description additionalProperties: false description: Request body for updating a project CreateProjectResponse: type: object properties: success: type: boolean data: $ref: '#/components/schemas/ProjectItem' required: - success - data additionalProperties: false description: The created project UpdateProjectResponse: type: object properties: success: type: boolean data: $ref: '#/components/schemas/ProjectItem' required: - success - data additionalProperties: false description: The updated project GetProjectResponse: type: object properties: success: type: boolean data: $ref: '#/components/schemas/ProjectItem' required: - success - data additionalProperties: false description: A single project DeleteProjectResponse: type: object properties: success: type: boolean data: $ref: '#/components/schemas/ProjectItem' required: - success - data additionalProperties: false description: The deleted (archived) project GetUsageResponse: type: object properties: success: type: boolean enum: - true data: $ref: '#/components/schemas/Usage' required: - success - data additionalProperties: false description: Org usage for a date range, in monthly buckets Usage: type: object properties: generated_at: type: string description: ISO-8601 timestamp the response was computed at start_date: type: string description: Calendar date, YYYY-MM-DD (UTC) end_date: type: string description: Calendar date, YYYY-MM-DD (UTC) buckets: type: array items: $ref: '#/components/schemas/UsageBucket' description: One bucket per calendar month in the range, through the current month. Every row is returned; there is no pagination required: - generated_at - start_date - end_date - buckets additionalProperties: false UsageBucket: type: object properties: start_date: type: string description: Inclusive bucket start end_date: type: string description: Exclusive bucket end results: type: array items: $ref: '#/components/schemas/UsageResult' required: - start_date - end_date - results additionalProperties: false UsageResult: type: object properties: workspace_id: type: string workspace_slug: type: string description: The workspace scope name workspace_label: type: string description: The workspace scope label, or the slug if the label is empty project_id: type: string project_slug: type: string description: The project scope name project_label: type: string description: The project scope label, or the slug if the label is empty event_type: type: string event_count: type: integer minimum: 0 metrics_computed_count: type: integer minimum: 0 description: Number of metrics.* keys on the events required: - event_type - event_count - metrics_computed_count additionalProperties: false GetUsageCurrentResponse: type: object properties: success: type: boolean enum: - true data: $ref: '#/components/schemas/UsageCurrent' required: - success - data additionalProperties: false description: Point-in-time org counts UsageCurrent: type: object properties: as_of: type: string description: ISO-8601 timestamp the counts were read at user_count: type: integer minimum: 0 description: Members who completed onboarding workspace_count: type: integer minimum: 0 description: Non-archived workspaces project_count: type: integer minimum: 0 description: Non-archived projects required: - as_of - user_count - workspace_count - project_count additionalProperties: false VirtualDataplaneItem: type: object properties: id: type: string name: type: string description: Virtual dataplane display name cluster_id: type: string description: Identifier of the physical cluster hosting this dataplane created_at: anyOf: - type: string format: date-time - type: string updated_at: anyOf: - type: string format: date-time - type: string required: - id - name - cluster_id - created_at - updated_at additionalProperties: false description: Virtual dataplane object PostVirtualDataplaneRequest: type: object properties: name: type: string maxLength: 200 description: Virtual dataplane display name. Allowed characters are the letters A-Z and a-z (no accented letters), digits, space, underscore, hyphen, apostrophe and ampersand. The name must contain at least one of those letters or a digit, and must not start with a space. slug: type: string minLength: 1 maxLength: 200 description: Globally unique identifier for the virtual dataplane, letters, digits and underscores only. Omit it and the server derives one from the name with a random suffix appended. A slug already in use returns 409. cluster_id: type: string minLength: 1 description: Physical cluster to host this virtual dataplane. Omit to place it alongside the existing virtual dataplanes in this org; required when the org has none yet, or when its virtual dataplanes span more than one cluster. dataplane_creator: type: string format: email description: Email of the user to grant the dataplane-creator membership to (API key actors only). A signed-in user does not see the new dataplane until their session refreshes, which happens on their next request to the control plane. required: - name additionalProperties: false description: Request body for creating a virtual dataplane PutVirtualDataplaneRequest: type: object properties: name: type: string maxLength: 200 description: Virtual dataplane display name. Allowed characters are the letters A-Z and a-z (no accented letters), digits, space, underscore, hyphen, apostrophe and ampersand. The name must contain at least one of those letters or a digit, and must not start with a space. additionalProperties: false description: Request body for updating a virtual dataplane CreateVirtualDataplaneResponse: type: object properties: success: type: boolean data: $ref: '#/components/schemas/VirtualDataplaneItem' required: - success - data additionalProperties: false description: The created virtual dataplane GetVirtualDataplaneResponse: type: object properties: success: type: boolean data: $ref: '#/components/schemas/VirtualDataplaneItem' required: - success - data additionalProperties: false description: A single virtual dataplane UpdateVirtualDataplaneResponse: type: object properties: success: type: boolean data: $ref: '#/components/schemas/VirtualDataplaneItem' required: - success - data additionalProperties: false description: The updated virtual dataplane DeleteVirtualDataplaneResponse: type: object properties: success: type: boolean data: $ref: '#/components/schemas/VirtualDataplaneItem' required: - success - data additionalProperties: false description: The deleted (archived) virtual dataplane. Descendants archived by the cascade are not listed. WorkspaceItem: type: object properties: id: type: string name: type: string description: Workspace display name description: type: string description: Workspace description created_at: anyOf: - type: string format: date-time - type: string updated_at: anyOf: - type: string format: date-time - type: string - type: 'null' required: - id - name - description - created_at additionalProperties: false description: Workspace object PostWorkspaceRequest: type: object properties: name: type: string maxLength: 200 description: Workspace display name. Allowed characters are the letters A-Z and a-z (no accented letters), digits, space, underscore, hyphen, apostrophe and ampersand. The name must contain at least one of those letters or a digit, and must not start with a space. slug: type: string minLength: 1 maxLength: 200 description: Globally unique identifier for the workspace, letters, digits and underscores only. Omit it and the server derives one from the name with a random suffix appended. Supply it when the identifier has to match a value maintained outside HoneyHive, such as an identity provider group that grants access to this workspace. A slug already in use returns 409. description: type: string description: Workspace description workspace_creator: type: string format: email description: Email of the user to grant the workspace-creator membership to (API key actors only). A signed-in user does not see the new workspace until their session refreshes, which happens on their next request to the control plane. required: - name additionalProperties: false description: Request body for creating a workspace PutWorkspaceRequest: type: object properties: name: type: string maxLength: 200 description: Workspace display name. Allowed characters are the letters A-Z and a-z (no accented letters), digits, space, underscore, hyphen, apostrophe and ampersand. The name must contain at least one of those letters or a digit, and must not start with a space. description: type: string description: Workspace description additionalProperties: false description: Request body for updating a workspace CreateWorkspaceResponse: type: object properties: success: type: boolean data: $ref: '#/components/schemas/WorkspaceItem' required: - success - data additionalProperties: false description: The created workspace GetWorkspaceResponse: type: object properties: success: type: boolean data: $ref: '#/components/schemas/WorkspaceItem' required: - success - data additionalProperties: false description: A single workspace UpdateWorkspaceResponse: type: object properties: success: type: boolean data: $ref: '#/components/schemas/WorkspaceItem' required: - success - data additionalProperties: false description: The updated workspace DeleteWorkspaceResponse: type: object properties: success: type: boolean data: $ref: '#/components/schemas/WorkspaceItem' required: - success - data additionalProperties: false description: The deleted (archived) workspace. Descendants archived by the cascade are not listed. AlertItemThresholdsCritical: type: object properties: operator: type: string enum: - greater_than - less_than - equal_to value: type: number required: - operator - value additionalProperties: false AlertItemThresholdsResolved: type: object properties: operator: type: string enum: - greater_than - less_than - equal_to value: type: number required: - operator - value additionalProperties: false AlertItemThresholds: type: object properties: critical: $ref: '#/components/schemas/AlertItemThresholdsCritical' resolved: $ref: '#/components/schemas/AlertItemThresholdsResolved' required: - critical - resolved additionalProperties: false AlertItemLastResultThresholdsCritical: type: object properties: operator: type: string enum: - greater_than - less_than - equal_to value: type: number required: - operator - value additionalProperties: false AlertItemLastResultThresholdsResolved: type: object properties: operator: type: string enum: - greater_than - less_than - equal_to value: type: number required: - operator - value additionalProperties: false AlertItemLastResultThresholds: type: object properties: critical: $ref: '#/components/schemas/AlertItemLastResultThresholdsCritical' resolved: $ref: '#/components/schemas/AlertItemLastResultThresholdsResolved' required: - critical - resolved additionalProperties: false AlertTriggerResultThresholdsCritical: type: object properties: operator: type: string enum: - greater_than - less_than - equal_to value: type: number required: - operator - value additionalProperties: false AlertTriggerResultThresholdsResolved: type: object properties: operator: type: string enum: - greater_than - less_than - equal_to value: type: number required: - operator - value additionalProperties: false AlertTriggerResultThresholds: type: object properties: critical: $ref: '#/components/schemas/AlertTriggerResultThresholdsCritical' resolved: $ref: '#/components/schemas/AlertTriggerResultThresholdsResolved' required: - critical - resolved additionalProperties: false AlertTriggerResult: type: object properties: current_bucket_score: anyOf: - type: number - type: boolean previous_bucket_score: anyOf: - type: number - type: boolean last_triggered_baseline: anyOf: - type: number - type: boolean drift_percentage: type: number thresholds: $ref: '#/components/schemas/AlertTriggerResultThresholds' event_filters: type: array items: {} event_metrics: type: array items: {} aggregation: type: string additionalProperties: {} AlertNotificationMembershipUser: type: object properties: id: type: string required: - id additionalProperties: false PostAlertRequestThresholdsCritical: type: object properties: operator: type: string enum: - greater_than - less_than - equal_to value: type: number required: - operator - value additionalProperties: false PostAlertRequestThresholdsResolved: type: object properties: operator: type: string enum: - greater_than - less_than - equal_to value: type: number required: - operator - value additionalProperties: false PostAlertRequestThresholds: type: object properties: critical: $ref: '#/components/schemas/PostAlertRequestThresholdsCritical' resolved: $ref: '#/components/schemas/PostAlertRequestThresholdsResolved' required: - critical - resolved additionalProperties: false PostAlertRequestNotificationDetailsCritical: type: object properties: channel: type: string enum: - EMAIL - SLACK - WEBHOOK scope: type: string enum: - ALL_PROJECT_MEMBERS - SPECIFIC_MEMBER user_ids: type: array items: type: string metadata: type: object additionalProperties: {} required: - channel - scope - metadata additionalProperties: false PostAlertRequestNotificationDetailsResolved: type: object properties: channel: type: string enum: - EMAIL - SLACK - WEBHOOK scope: type: string enum: - ALL_PROJECT_MEMBERS - SPECIFIC_MEMBER user_ids: type: array items: type: string metadata: type: object additionalProperties: {} required: - channel - scope - metadata additionalProperties: false PostAlertRequestNotificationDetails: type: object properties: critical: $ref: '#/components/schemas/PostAlertRequestNotificationDetailsCritical' resolved: $ref: '#/components/schemas/PostAlertRequestNotificationDetailsResolved' required: - critical - resolved additionalProperties: false