{
  "openapi": "3.1.0",
  "info": {
    "title": "SparkLogs REST API",
    "version": "1",
    "description": "Send the credential in the `Authorization` header of every call: `Authorization: Bearer <token>`.\nEach API token may make 1,200 calls a minute. A call over the limit returns 429 with `Retry-After`.\nA field not selected is absent from the response. A selected field with no value is null. `fields` selects the fields of each object only: the response's own fields, `message`, and on a paged list `next_cursor`, on one that syncs `watermark` and on one whose objects hold a value worked out from the clock `as_of`, are sent whatever it names.\nAn update changes the fields its body sends and keeps every field it leaves out. `null` clears a field; on a field that cannot be empty, such as a name, it returns 400 naming the field. An empty string clears a text field that can be empty and stores no value, so the field reads back as null. Each field of an update states what `null` and an empty string do. An object field merged by key, such as `custom_fields`, follows the same rule for each key: a key left out keeps its value, `null` removes it.",
    "termsOfService": "https://sparklogs.com/docs/legal/terms-of-service",
    "contact": {
      "email": "help@sparklogs.com"
    }
  },
  "servers": [
    {
      "url": "https://engine.sparklogs.app/app-api",
      "description": "The SparkLogs API."
    }
  ],
  "security": [
    {
      "bearer": []
    }
  ],
  "tags": [
    {
      "name": "workspaces",
      "description": "A workspace holds your organizations, agents, people and settings; read it and change its name, onboarding and ingest policy."
    },
    {
      "name": "credential",
      "description": "The credential that authenticates a call: read what it is and which workspace it belongs to, or give a token a new secret."
    },
    {
      "name": "access",
      "description": "Every privilege your credential holds in a workspace, and where it holds it."
    },
    {
      "name": "users",
      "description": "The profile of the person a personal token or OAuth token acts as."
    },
    {
      "name": "regions",
      "description": "The regions a workspace's data can live in, with the addresses its data is sent to and queried at."
    },
    {
      "name": "roles",
      "description": "The roles a grant can give: the standard roles and the workspace's own, each with its privileges."
    },
    {
      "name": "members",
      "description": "The people in a workspace and its pending invitations, with their grants; list them or remove a member."
    },
    {
      "name": "invitations",
      "description": "An invitation asks a person by email to join the workspace with grants; create, send or withdraw one."
    },
    {
      "name": "grants",
      "description": "A grant gives a member, a group or a workspace token a role over a scope of organizations; give, change and remove them."
    },
    {
      "name": "groups",
      "description": "A group gives its grants to every member in it; list, create, rename and delete groups and set who is in them."
    },
    {
      "name": "organizations",
      "description": "Organizations are the tree your clients and sites live in; list, create, change, move, delete and restore them."
    },
    {
      "name": "agents",
      "description": "An agent is a SparkLogs Agent on a machine; list them, read one, count them by enrollment, activity, contact and collection, and rename, move, delete or restore one."
    },
    {
      "name": "ingest-keys",
      "description": "An ingest key lets a sender other than a SparkLogs Agent send log data for an organization; list and read them, create one, read or replace its secret, and rename, move, delete or restore one."
    },
    {
      "name": "registration-tokens",
      "description": "A registration token lets agent installers register new agents into an organization; create, read, reveal, change, revoke, delete and restore them."
    },
    {
      "name": "agent-releases",
      "description": "The agent build to install: where to download each installer, how to check it, and the command that installs it."
    },
    {
      "name": "audit-events",
      "description": "The audit log records every change and every refusal in the workspace, with who did it and with which credential."
    },
    {
      "name": "replication-targets",
      "description": "A replication target is your own storage the workspace's archived data is copied to; list the targets and how their latest copies went."
    }
  ],
  "paths": {
    "/credential": {
      "get": {
        "operationId": "readCredential",
        "tags": [
          "credential"
        ],
        "summary": "Read credential metadata",
        "description": "Returns what the credential on this request is: a session, or an API token with its id, the one workspace it belongs to, that workspace's region, its scopes and when it expires. A workspace token calls it to learn its workspace id.\n\nAccess: Needs no privilege: it reads only the credential that authenticates the call.\n\nFields sent by default: kind, credential_id, workspace_id, region_id, scope_restriction, scopes, expires_at.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": []
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [],
        "parameters": [
          {
            "name": "fields",
            "in": "query",
            "description": "Comma-separated top-level fields of each object to return instead of the default set.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false
          }
        ],
        "responses": {
          "200": {
            "description": "Read credential metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "credential": {
                      "$ref": "#/components/schemas/Credential",
                      "description": "The credential."
                    },
                    "message": {
                      "type": "string",
                      "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
                    }
                  },
                  "required": [
                    "credential",
                    "message"
                  ]
                },
                "examples": {
                  "workspace-token": {
                    "summary": "Learn the workspace a deployment token belongs to",
                    "value": {
                      "credential": {
                        "kind": "workspace_key",
                        "credential_id": "4b1d0000-0000-4000-8000-000000000803",
                        "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                        "region_id": "us-central",
                        "scope_restriction": "listed",
                        "scopes": [
                          "workspace:read",
                          "fleet:deploy"
                        ],
                        "expires_at": "2027-11-10T09:00:00Z"
                      },
                      "message": "credential retrieved"
                    }
                  },
                  "psa-token": {
                    "summary": "Learn the workspace a PSA integration's token belongs to",
                    "value": {
                      "credential": {
                        "kind": "workspace_key",
                        "credential_id": "4b1d0000-0000-4000-8000-000000000801",
                        "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                        "region_id": "us-central",
                        "scope_restriction": "listed",
                        "scopes": [
                          "workspace:read",
                          "fleet:write"
                        ],
                        "expires_at": "2027-11-01T09:00:00Z"
                      },
                      "message": "credential retrieved"
                    }
                  },
                  "personal-read-only": {
                    "summary": "Read a personal token created with only workspace:read",
                    "value": {
                      "credential": {
                        "kind": "user_key",
                        "credential_id": "4b1d0000-0000-4000-8000-000000000802",
                        "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                        "region_id": "us-central",
                        "scope_restriction": "listed",
                        "scopes": [
                          "workspace:read"
                        ],
                        "expires_at": "2026-12-10T16:00:00Z"
                      },
                      "message": "credential retrieved"
                    }
                  },
                  "personal-unlimited": {
                    "summary": "Read a personal token created without scope limits",
                    "value": {
                      "credential": {
                        "kind": "user_key",
                        "credential_id": "4b1d0000-0000-4000-8000-000000000802",
                        "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                        "region_id": "us-central",
                        "scope_restriction": "none",
                        "scopes": [
                          "workspace:read",
                          "events:query",
                          "events:read",
                          "devices:read",
                          "analytics:read",
                          "admin:read",
                          "fleet:deploy",
                          "fleet:write",
                          "admin:write",
                          "admin:delegate"
                        ],
                        "expires_at": null
                      },
                      "message": "credential retrieved"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, one given twice, or `fields` naming a field it does not have.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "revoked": {
                    "summary": "A token that was revoked",
                    "value": {
                      "error": "the API token is not valid",
                      "error_code": "APP_API_ERR_UNAUTHORIZED"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/credential/rotate": {
      "post": {
        "operationId": "rotateCredential",
        "tags": [
          "credential"
        ],
        "summary": "Rotate the credential's secret",
        "description": "Gives the personal token or workspace token that authenticates this call a new secret and returns it, once. The old secret stops working at once on this API, and `cache_clear_status` says whether every other SparkLogs service refuses it. The token's id, label, scopes, grants and expiry stay. When the token was revoked, deleted or rotated while the call ran, nothing changes and the call returns 409. The rotation is recorded in the audit log. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 15 minutes.\n\nAccess: Needs no privilege: the token that authenticates the call acts on itself and nothing else.\n\nUnknown input: An unknown or repeated query parameter returns 400. It takes no body: a body field returns 400.\n\nSecret: The response carries a secret and is sent with `Cache-Control: no-store`. Keep it out of caches and logs.",
        "security": [
          {
            "bearer": []
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "user_key",
          "workspace_key"
        ],
        "x-privileges": [],
        "x-returns-secret": true,
        "responses": {
          "200": {
            "description": "Rotate the credential's secret",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CredentialRotated"
                },
                "examples": {
                  "rotate": {
                    "summary": "Give the presented deployment token a new secret",
                    "value": {
                      "message": "token rotated",
                      "credential_id": "4b1d0000-0000-4000-8000-000000000803",
                      "token": "sl_us_EXAMPLE_NOT_A_REAL_TOKEN",
                      "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                      "user_id": null,
                      "label": "RMM deployment",
                      "scope_restriction": "listed",
                      "scopes": [
                        "workspace:read",
                        "fleet:deploy"
                      ],
                      "expires_at": "2027-11-10T09:00:00Z",
                      "cache_clear_by_region": {
                        "us-central": "ok"
                      },
                      "cache_clear_status": "ok"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, or names a field: the call takes none.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_CREDENTIAL_NOT_ADMITTED`: The call does not take a credential of this kind: `session`, `oauth`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`APP_API_ERR_CONFLICT`: The token was revoked, deleted or expired, or rotated by another call while this one ran.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/regions": {
      "get": {
        "operationId": "listRegions",
        "tags": [
          "regions"
        ],
        "summary": "List regions",
        "description": "Returns every region a workspace's data can live in, in sort order, with the addresses its data is sent to and queried at.\n\nAccess: Needs no privilege: every caller gets the same list of regions.\n\nFields sent by default: id, name, sort_order, ingest_uri, query_uri. Sent only when named: bigquery_location.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": []
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [],
        "parameters": [
          {
            "name": "fields",
            "in": "query",
            "description": "Comma-separated top-level fields of each object to return instead of the default set.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false
          }
        ],
        "responses": {
          "200": {
            "description": "List regions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "regions": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Region"
                      },
                      "description": "Every one of the regions you can see."
                    },
                    "message": {
                      "type": "string",
                      "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
                    }
                  },
                  "required": [
                    "regions",
                    "message"
                  ]
                },
                "examples": {
                  "list": {
                    "summary": "List the regions",
                    "value": {
                      "message": "regions retrieved",
                      "regions": [
                        {
                          "id": "us-central",
                          "name": "United States",
                          "sort_order": 1,
                          "ingest_uri": "https://ingest-usc1.engine.sparklogs.app",
                          "query_uri": "https://query-usc1.engine.sparklogs.app"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, one given twice, or `fields` naming a field it does not have.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/users/{user_id}": {
      "get": {
        "operationId": "readUser",
        "tags": [
          "users"
        ],
        "summary": "Read your profile",
        "description": "Returns the profile of the person the credential acts as: your user id, email and names. Any other user id returns 404. A workspace token acts as no person and is refused.\n\nAccess: Needs no privilege: it reads only the profile of the person the credential acts as.\n\nFields sent by default: id, email, full_name, display_name.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": []
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth"
        ],
        "x-privileges": [],
        "parameters": [
          {
            "name": "user_id",
            "in": "path",
            "required": true,
            "description": "The user's id.",
            "schema": {
              "type": "string"
            },
            "examples": {
              "self": {
                "summary": "Read your own profile",
                "value": "AlexRiveraExampleUserId00001"
              }
            }
          },
          {
            "name": "fields",
            "in": "query",
            "description": "Comma-separated top-level fields of each object to return instead of the default set.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false
          }
        ],
        "responses": {
          "200": {
            "description": "Read your profile",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "user": {
                      "$ref": "#/components/schemas/User",
                      "description": "The user."
                    },
                    "message": {
                      "type": "string",
                      "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
                    }
                  },
                  "required": [
                    "user",
                    "message"
                  ]
                },
                "examples": {
                  "self": {
                    "summary": "Read your own profile",
                    "value": {
                      "message": "user retrieved",
                      "user": {
                        "id": "AlexRiveraExampleUserId00001",
                        "email": "alex.rivera@example.com",
                        "full_name": "Alex Rivera",
                        "display_name": "Alex"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, one given twice, or `fields` naming a field it does not have.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_CREDENTIAL_NOT_ADMITTED`: The call does not take a credential of this kind: `workspace_key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`APP_API_ERR_RECORD_NOT_FOUND`: The user id is not the caller's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}": {
      "patch": {
        "operationId": "updateWorkspace",
        "tags": [
          "workspaces"
        ],
        "summary": "Update a workspace",
        "description": "Changes the workspace's name and description; a field left out keeps its value. Needs `workspace.write`.\n\nAccess: Needs `workspace.write`. `workspace.write` applies to the workspace itself: a grant over every organization, or over the workspace, carries it.\n\nUnknown input: An unknown or repeated query parameter returns 400. An unknown body field returns 400.",
        "security": [
          {
            "bearer": [
              "admin:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "workspace.write"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "describe": {
                "summary": "Change the workspace's description",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkspaceUpdate"
              },
              "examples": {
                "describe": {
                  "summary": "Change the workspace's description",
                  "value": {
                    "description": "Managed IT for clinics, dental and accounting offices"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update a workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceUpdated"
                },
                "examples": {
                  "describe": {
                    "summary": "Change the workspace's description",
                    "value": {
                      "message": "workspace updated"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`.\n`APP_API_ERR_BAD_PARAMETERS`: `name` is empty.\n`APP_API_ERR_PARAMETER_TOO_LONG`: `name` is longer than 128 characters, or `description` longer than 2048.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `workspace.write`. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "readWorkspace",
        "tags": [
          "workspaces"
        ],
        "summary": "Read a workspace",
        "description": "Returns the workspace's settings and state: its name, region, service plan, retention and trial. `usage` needs `ingestion.read` and `storage` needs `archive.config.read`, each across the whole workspace; naming either in `fields` without it returns 403.\n\nAccess: Needs `workspace.read`. Any grant in the workspace carries `workspace.read`.\n\nFields sent by default: id, name, description, region, plan, data_initialized, retention_hours, trial_expires_at, app_analytics_provisioned, deleted_at, updated_at. Sent only when named: usage, storage, settings, job_statuses, agent_rollout_ring. Needing a further privilege: usage needs ingestion.read; storage needs archive.config.read.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": [
              "workspace:read"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "workspace.read"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "read": {
                "summary": "Read the workspace",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "fields",
            "in": "query",
            "description": "Comma-separated top-level fields of each object to return instead of the default set.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false
          }
        ],
        "responses": {
          "200": {
            "description": "Read a workspace",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "workspace": {
                      "$ref": "#/components/schemas/Workspace",
                      "description": "The workspace."
                    },
                    "message": {
                      "type": "string",
                      "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
                    }
                  },
                  "required": [
                    "workspace",
                    "message"
                  ]
                },
                "examples": {
                  "read": {
                    "summary": "Read the workspace",
                    "value": {
                      "message": "workspace retrieved",
                      "workspace": {
                        "id": "5e1f0a00-0000-4000-8000-000000000001",
                        "name": "Northwind IT Services",
                        "description": "Managed IT for clinics and small offices",
                        "region": {
                          "id": "us-central",
                          "name": "United States",
                          "sort_order": 1,
                          "ingest_uri": "https://ingest-usc1.engine.sparklogs.app",
                          "query_uri": "https://query-usc1.engine.sparklogs.app",
                          "bigquery_location": "US"
                        },
                        "plan": {
                          "id": "sparklogs_cloud",
                          "name": "SparkLogs Cloud",
                          "description": null,
                          "sort_order": 10,
                          "data_engine_id": "bigquery",
                          "is_billable": true,
                          "max_retention_hours": 8760,
                          "self_hosted_querying": false,
                          "allow_custom_query_scanned_limit": true
                        },
                        "data_initialized": true,
                        "retention_hours": 2160,
                        "trial_expires_at": null,
                        "app_analytics_provisioned": false,
                        "deleted_at": null,
                        "updated_at": "2026-11-10T06:00:00Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, one given twice, or `fields` naming a field it does not have.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `workspace.read`. The same refusal comes when the path names a workspace other than the token's own.\n`APP_API_ERR_NO_PRIVILEGE`: `fields` names `usage` without `ingestion.read`, or `storage` without `archive.config.read`, across the whole workspace.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/access": {
      "get": {
        "operationId": "readAccess",
        "tags": [
          "access"
        ],
        "summary": "Read your access in a workspace",
        "description": "Returns every privilege your credential holds in the workspace, and where. For an API token it is the token's own access, inside its scopes and organization limits, never the whole access of the person behind it.\n\nAccess: Needs `workspace.read`. Any grant in the workspace carries `workspace.read`.\n\nFields sent by default: privileges, credential.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": [
              "workspace:read"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "workspace.read"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "read": {
                "summary": "Read what the token may do",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "fields",
            "in": "query",
            "description": "Comma-separated top-level fields of each object to return instead of the default set.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false
          }
        ],
        "responses": {
          "200": {
            "description": "Read your access in a workspace",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "access": {
                      "$ref": "#/components/schemas/Access",
                      "description": "The access."
                    },
                    "message": {
                      "type": "string",
                      "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
                    }
                  },
                  "required": [
                    "access",
                    "message"
                  ]
                },
                "examples": {
                  "read": {
                    "summary": "Read what the token may do",
                    "value": {
                      "access": {
                        "privileges": [
                          {
                            "id": "organization.read",
                            "level": "org",
                            "scope": {
                              "kind": "selected",
                              "org_ids": [
                                "0a9e0000-0000-4000-8000-000000000101",
                                "0a9e0000-0000-4000-8000-000000000105"
                              ],
                              "inherited": false,
                              "other_orgs": false
                            }
                          },
                          {
                            "id": "workspace.read",
                            "level": "self",
                            "scope": null
                          }
                        ],
                        "credential": {
                          "kind": "workspace_key",
                          "credential_id": "4b1d0000-0000-4000-8000-000000000804",
                          "scope_restriction": "listed",
                          "scopes": [
                            "workspace:read"
                          ]
                        }
                      },
                      "message": "access retrieved"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, one given twice, or `fields` naming a field it does not have.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `workspace.read`. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/agent-release": {
      "get": {
        "operationId": "readAgentRelease",
        "tags": [
          "agent-releases"
        ],
        "summary": "Read the agent release",
        "description": "Returns the SparkLogs Agent build the workspace's update ring publishes now, which during a staged rollout is the build being rolled out: its version, the EXE and MSI with each file's URL, SHA-256 and size, the signer of their Authenticode signature, and a silent install command for each. Answered only once SparkLogs' signature on the release verifies. The commands hold placeholders, never a secret: `reveal-registration-token` reads the token.\n\nAccess: Needs `workspace.read`. Any grant in the workspace carries `workspace.read`.\n\nFields sent by default: ring, target, version, publisher, installers.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": [
              "workspace:read"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "workspace.read"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "read": {
                "summary": "Read the agent build to install and its install commands",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "not-verified": {
                "summary": "A release whose signature did not verify",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "fields",
            "in": "query",
            "description": "Comma-separated top-level fields of each object to return instead of the default set.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false
          }
        ],
        "responses": {
          "200": {
            "description": "Read the agent release",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_release": {
                      "$ref": "#/components/schemas/AgentRelease",
                      "description": "The agent release."
                    },
                    "message": {
                      "type": "string",
                      "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
                    }
                  },
                  "required": [
                    "agent_release",
                    "message"
                  ]
                },
                "examples": {
                  "read": {
                    "summary": "Read the agent build to install and its install commands",
                    "value": {
                      "agent_release": {
                        "ring": "early_access",
                        "target": "windows_x86_64",
                        "version": "1.14.15",
                        "publisher": "IT Lightning, LLC",
                        "installers": [
                          {
                            "kind": "exe",
                            "file_name": "SparkLogsAgentSetup-x64-1.14.15.exe",
                            "url": "https://cdn.sparklogs.app/agent/data/1.14.15/windows_x86_64/sha256_5e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e7/SparkLogsAgentSetup-x64-1.14.15.exe",
                            "sha256": "5e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e7",
                            "size_bytes": 15556216,
                            "command": "SparkLogsAgentSetup-x64-1.14.15.exe /qn /norestart EULA=ACCEPT REGISTRATION_TOKEN=\"\u003cREGISTRATION_TOKEN\u003e\" RMMCLIENTID=\"\u003cRMMCLIENTID\u003e\" PSACLIENTID=\"\u003cPSACLIENTID\u003e\" CLIENTNAME=\"\u003cCLIENTNAME\u003e\" RMMDEVICEID=\"\u003cRMMDEVICEID\u003e\" PSADEVICEID=\"\u003cPSADEVICEID\u003e\""
                          },
                          {
                            "kind": "msi",
                            "file_name": "SparkLogsAgent-x64-1.14.15.msi",
                            "url": "https://cdn.sparklogs.app/agent/data/1.14.15/windows_x86_64/sha256_a9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1f/SparkLogsAgent-x64-1.14.15.msi",
                            "sha256": "a9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1fa9e75e1f",
                            "size_bytes": 19189760,
                            "command": "msiexec /i SparkLogsAgent-x64-1.14.15.msi /qn /norestart EULA=ACCEPT REGISTRATION_TOKEN=\"\u003cREGISTRATION_TOKEN\u003e\" RMMCLIENTID=\"\u003cRMMCLIENTID\u003e\" PSACLIENTID=\"\u003cPSACLIENTID\u003e\" CLIENTNAME=\"\u003cCLIENTNAME\u003e\" RMMDEVICEID=\"\u003cRMMDEVICEID\u003e\" PSADEVICEID=\"\u003cPSADEVICEID\u003e\" /l*v %TEMP%\\SparkLogsAgent-install.log"
                          }
                        ]
                      },
                      "message": "agent release retrieved"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, one given twice, or `fields` naming a field it does not have.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `workspace.read`. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`APP_API_ERR_RECORD_NOT_FOUND`: No build is published for the workspace's update ring.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "`APP_API_ERR_AGENT_RELEASE_UNAVAILABLE`: The release could not be read, or its signature did not verify.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not-verified": {
                    "summary": "A release whose signature did not verify",
                    "value": {
                      "error": "the agent release could not be read and verified",
                      "error_code": "APP_API_ERR_AGENT_RELEASE_UNAVAILABLE"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_NOT_CONFIGURED`: This server is not configured to read agent releases.\n`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/agents": {
      "get": {
        "operationId": "listAgents",
        "tags": [
          "agents"
        ],
        "summary": "List agents",
        "description": "Returns the SparkLogs Agents you can see, a page at a time, in `id` order. Seeing an agent takes `organization.read` and `agent.read` at its organization. Filter by organization, with or without the organizations below it, by id, status, inactivity, host, device id or registration token; filters combine, a row passing every one given. `agent_status` and a moving `inactive_before` cutoff, such as 14 days before now, are worked out at the walk's `as_of`, the same instant for every page. `host_metadata`, `agent_data` and `custom_fields` are sent only when `fields` names them, at most 500 agents a page.\n\nAccess: Needs `agent.read`. `agent.read` applies at each organization a grant covers and every organization below it. `agent.read` also admits reading ingest keys, but never their secrets. A caller who reaches no organization gets an empty list.\n\nFields sent by default: id, workspace_id, name, organization_id, path, reported_state, agent_status, reported_state_changed_at, collection_status, stuck_reason, last_data_at, last_heartbeat_at, host_class, reported_hostname, rmm_device_id, psa_device_id, agent_version, os_family, os_version, created_at, updated_at, deleted_at, organization_deleted_at. Sent only when named: description, collection_detail, collection_feeds, update_status, update_failure_reason, install_id, synthetic_install_id, rollout_seed, arch, host_roles, registration_token_id, cloned_from_agent_id, feed_pack_version, last_meta_at, deletion. Heavy, sent only when named: custom_fields, host_metadata, agent_data.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": [
              "workspace:read"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "agent.read"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "first-page": {
                "summary": "List every agent a read-only personal token can see",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "list": {
                "summary": "List the agents of Lakeside Clinic and below",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "by-registration-token": {
                "summary": "List the agents that registered with Lakeside Clinic's rollout token",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "by-clients-token": {
                "summary": "List the agents that registered with the token for every client",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "not-online": {
                "summary": "List the agents that are not online",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "collection-attention": {
                "summary": "List the agents whose collection is not healthy, with what a dashboard shows of each",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "every-agent": {
                "summary": "List every agent, a thousand a page",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "call-limit": {
                "summary": "A token over its call limit",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "address-limit": {
                "summary": "A call from an address that sent too many tokens that are not valid",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "organization_id",
            "in": "query",
            "description": "Only agents of this organization.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "list": {
                "summary": "List the agents of Lakeside Clinic and below",
                "value": "0a9e0000-0000-4000-8000-000000000101"
              }
            }
          },
          {
            "name": "subtree",
            "in": "query",
            "description": "`true` adds the agents of every organization below `organization_id`. `true` and `false` are the only values it takes.",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "examples": {
              "list": {
                "summary": "List the agents of Lakeside Clinic and below",
                "value": true
              }
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Only the agents with these ids. A comma-separated list of at most 100 ids matches any of them.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false,
            "x-filter": {
              "kind": "in",
              "clock": false,
              "with_updated_since": false
            }
          },
          {
            "name": "agent_status",
            "in": "query",
            "description": "Only agents reading one of these `agent_status` values. Deleted agents are listed with `deleted`, not here. A comma-separated list matches any of its values. Worked out at the walk's `as_of`.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "online",
                  "offline",
                  "never_seen",
                  "stopped",
                  "system_shutdown",
                  "uninstalled",
                  "upgrading_overdue"
                ]
              }
            },
            "style": "form",
            "explode": false,
            "x-filter": {
              "kind": "in",
              "clock": true,
              "with_updated_since": false
            },
            "examples": {
              "not-online": {
                "summary": "List the agents that are not online",
                "value": [
                  "offline",
                  "never_seen",
                  "stopped",
                  "system_shutdown",
                  "uninstalled",
                  "upgrading_overdue"
                ]
              }
            }
          },
          {
            "name": "collection_status",
            "in": "query",
            "description": "Only agents reporting one of these `collection_status` values, the same buckets `read-agent-summary` counts. A comma-separated list matches any of its values.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "healthy",
                  "behind",
                  "onboarding",
                  "degraded",
                  "unknown",
                  "none"
                ]
              }
            },
            "style": "form",
            "explode": false,
            "x-filter": {
              "kind": "in",
              "clock": false,
              "with_updated_since": false
            },
            "examples": {
              "collection-attention": {
                "summary": "List the agents whose collection is not healthy, with what a dashboard shows of each",
                "value": [
                  "behind",
                  "degraded",
                  "unknown",
                  "none"
                ]
              }
            }
          },
          {
            "name": "inactive_before",
            "in": "query",
            "description": "Only agents that were created, last sent data, last checked in and last changed status before this time: what `inactive` counts on `read-agent-summary`, at a cutoff you choose. An RFC 3339 time.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "x-filter": {
              "kind": "before",
              "clock": false,
              "with_updated_since": false
            }
          },
          {
            "name": "host_class",
            "in": "query",
            "description": "Only agents of these `host_class` values, such as server. A value no agent reports matches nothing. A comma-separated list matches any of its values, each exactly and ignoring case. Spaces around the value are ignored.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false,
            "x-filter": {
              "kind": "in_fold",
              "clock": false,
              "with_updated_since": false
            }
          },
          {
            "name": "install_id",
            "in": "query",
            "description": "Only agents with this `install_id`: every record of one machine, such as the live one a refused restore or move conflicts with. Spaces around the value are ignored.",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "kind": "eq",
              "clock": false,
              "with_updated_since": false
            }
          },
          {
            "name": "reported_hostname",
            "in": "query",
            "description": "Only agents whose `reported_hostname` is this. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "kind": "eq_fold",
              "clock": false,
              "with_updated_since": false
            }
          },
          {
            "name": "registration_token_id",
            "in": "query",
            "description": "Only agents that registered with this registration token.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "x-filter": {
              "kind": "eq",
              "clock": false,
              "with_updated_since": false
            },
            "examples": {
              "by-registration-token": {
                "summary": "List the agents that registered with Lakeside Clinic's rollout token",
                "value": "7e0c0000-0000-4000-8000-000000000301"
              },
              "by-clients-token": {
                "summary": "List the agents that registered with the token for every client",
                "value": "7e0c0000-0000-4000-8000-000000000303"
              }
            }
          },
          {
            "name": "rmm_device_id",
            "in": "query",
            "description": "Only agents recording this `rmm_device_id`; every one is returned. Spaces around the value are ignored.",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "kind": "eq",
              "clock": false,
              "with_updated_since": false
            }
          },
          {
            "name": "psa_device_id",
            "in": "query",
            "description": "Only agents recording this `psa_device_id`; every one is returned. Spaces around the value are ignored.",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "kind": "eq",
              "clock": false,
              "with_updated_since": false
            }
          },
          {
            "name": "deleted",
            "in": "query",
            "description": "Which agents to list, by whether they or their organization are deleted.",
            "schema": {
              "type": "string",
              "enum": [
                "exclude",
                "include",
                "only"
              ],
              "default": "exclude"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "How many agents a page holds: 1 to 5000, 1000 by default; at most 500, and 500 by default, with a heavy field.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 5000
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "The `next_cursor` of the previous page, with the same filters.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "description": "Comma-separated top-level fields of each object to return instead of the default set.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false,
            "examples": {
              "collection-attention": {
                "summary": "List the agents whose collection is not healthy, with what a dashboard shows of each",
                "value": [
                  "id",
                  "organization_id",
                  "reported_hostname",
                  "rmm_device_id",
                  "agent_status",
                  "collection_status",
                  "collection_detail",
                  "stuck_reason",
                  "last_data_at",
                  "last_heartbeat_at"
                ]
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List agents",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agents": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Agent"
                      },
                      "description": "The agents on this page."
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Null on the last page. Otherwise pass it as `cursor` for the next page."
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time",
                      "description": "The instant this walk's values worked out from the clock, and its filters on them, are worked out at: fixed on the first page and the same on every page after it."
                    },
                    "message": {
                      "type": "string",
                      "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
                    }
                  },
                  "required": [
                    "agents",
                    "next_cursor",
                    "as_of",
                    "message"
                  ]
                },
                "examples": {
                  "first-page": {
                    "summary": "List every agent a read-only personal token can see",
                    "value": {
                      "agents": [
                        {
                          "id": "a9e70000-0000-4000-8000-000000000203",
                          "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                          "name": "PD-EXAM-03",
                          "organization_id": "0a9e0000-0000-4000-8000-000000000105",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000105",
                            "a9e70000-0000-4000-8000-000000000203"
                          ],
                          "reported_state": "stopped",
                          "agent_status": "stopped",
                          "reported_state_changed_at": "2026-11-09T18:00:00Z",
                          "collection_status": "unknown",
                          "stuck_reason": null,
                          "last_data_at": "2026-11-09T18:00:00Z",
                          "last_heartbeat_at": "2026-11-09T18:00:00Z",
                          "host_class": "workstation",
                          "reported_hostname": "pd-exam-03",
                          "rmm_device_id": null,
                          "psa_device_id": null,
                          "agent_version": "1.14.3",
                          "os_family": "windows",
                          "os_version": "10.0.22631",
                          "created_at": "2026-11-05T08:00:00Z",
                          "updated_at": "2026-11-09T18:00:00Z",
                          "deleted_at": null,
                          "organization_deleted_at": null
                        },
                        {
                          "id": "a9e70000-0000-4000-8000-000000000201",
                          "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                          "name": "FIN-LT-04",
                          "organization_id": "0a9e0000-0000-4000-8000-000000000102",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000101",
                            "0a9e0000-0000-4000-8000-000000000102",
                            "a9e70000-0000-4000-8000-000000000201"
                          ],
                          "reported_state": "running",
                          "agent_status": "online",
                          "reported_state_changed_at": "2026-11-03T12:00:00Z",
                          "collection_status": "healthy",
                          "stuck_reason": null,
                          "last_data_at": "2026-11-10T15:00:00Z",
                          "last_heartbeat_at": "2026-11-10T15:00:00Z",
                          "host_class": "workstation",
                          "reported_hostname": "fin-lt-04",
                          "rmm_device_id": null,
                          "psa_device_id": null,
                          "agent_version": "1.14.4",
                          "os_family": "windows",
                          "os_version": "10.0.22631",
                          "created_at": "2026-11-03T12:00:00Z",
                          "updated_at": "2026-11-10T15:00:00Z",
                          "deleted_at": null,
                          "organization_deleted_at": null
                        },
                        {
                          "id": "a9e70000-0000-4000-8000-000000000202",
                          "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                          "name": "wb-pc-04",
                          "organization_id": "0a9e0000-0000-4000-8000-000000000103",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000103",
                            "a9e70000-0000-4000-8000-000000000202"
                          ],
                          "reported_state": "running",
                          "agent_status": "online",
                          "reported_state_changed_at": "2026-11-04T09:00:00Z",
                          "collection_status": "behind",
                          "stuck_reason": null,
                          "last_data_at": "2026-11-10T14:00:00Z",
                          "last_heartbeat_at": "2026-11-10T15:00:00Z",
                          "host_class": "workstation",
                          "reported_hostname": "wb-pc-04",
                          "rmm_device_id": null,
                          "psa_device_id": null,
                          "agent_version": "1.14.4",
                          "os_family": "windows",
                          "os_version": "10.0.19045",
                          "created_at": "2026-11-04T09:00:00Z",
                          "updated_at": "2026-11-10T15:00:00Z",
                          "deleted_at": null,
                          "organization_deleted_at": null
                        }
                      ],
                      "as_of": "2026-11-10T15:05:00Z",
                      "message": "agents retrieved",
                      "next_cursor": null
                    }
                  },
                  "list": {
                    "summary": "List the agents of Lakeside Clinic and below",
                    "value": {
                      "agents": [
                        {
                          "id": "a9e70000-0000-4000-8000-000000000201",
                          "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                          "name": "FIN-LT-04",
                          "organization_id": "0a9e0000-0000-4000-8000-000000000102",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000101",
                            "0a9e0000-0000-4000-8000-000000000102",
                            "a9e70000-0000-4000-8000-000000000201"
                          ],
                          "reported_state": "running",
                          "agent_status": "online",
                          "reported_state_changed_at": "2026-11-03T12:00:00Z",
                          "collection_status": "healthy",
                          "stuck_reason": null,
                          "last_data_at": "2026-11-10T15:00:00Z",
                          "last_heartbeat_at": "2026-11-10T15:00:00Z",
                          "host_class": "workstation",
                          "reported_hostname": "fin-lt-04",
                          "rmm_device_id": null,
                          "psa_device_id": null,
                          "agent_version": "1.14.4",
                          "os_family": "windows",
                          "os_version": "10.0.22631",
                          "created_at": "2026-11-03T12:00:00Z",
                          "updated_at": "2026-11-10T15:00:00Z",
                          "deleted_at": null,
                          "organization_deleted_at": null
                        }
                      ],
                      "as_of": "2026-11-10T15:05:00Z",
                      "message": "agents retrieved",
                      "next_cursor": null
                    }
                  },
                  "by-registration-token": {
                    "summary": "List the agents that registered with Lakeside Clinic's rollout token",
                    "value": {
                      "agents": [
                        {
                          "id": "a9e70000-0000-4000-8000-000000000201",
                          "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                          "name": "FIN-LT-04",
                          "organization_id": "0a9e0000-0000-4000-8000-000000000102",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000101",
                            "0a9e0000-0000-4000-8000-000000000102",
                            "a9e70000-0000-4000-8000-000000000201"
                          ],
                          "reported_state": "running",
                          "agent_status": "online",
                          "reported_state_changed_at": "2026-11-03T12:00:00Z",
                          "collection_status": "healthy",
                          "stuck_reason": null,
                          "last_data_at": "2026-11-10T15:00:00Z",
                          "last_heartbeat_at": "2026-11-10T15:00:00Z",
                          "host_class": "workstation",
                          "reported_hostname": "fin-lt-04",
                          "rmm_device_id": null,
                          "psa_device_id": null,
                          "agent_version": "1.14.4",
                          "os_family": "windows",
                          "os_version": "10.0.22631",
                          "created_at": "2026-11-03T12:00:00Z",
                          "updated_at": "2026-11-10T15:00:00Z",
                          "deleted_at": null,
                          "organization_deleted_at": null
                        }
                      ],
                      "as_of": "2026-11-10T15:05:00Z",
                      "message": "agents retrieved",
                      "next_cursor": null
                    }
                  },
                  "by-clients-token": {
                    "summary": "List the agents that registered with the token for every client",
                    "value": {
                      "agents": [
                        {
                          "id": "a9e70000-0000-4000-8000-000000000202",
                          "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                          "name": "wb-pc-04",
                          "organization_id": "0a9e0000-0000-4000-8000-000000000103",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000103",
                            "a9e70000-0000-4000-8000-000000000202"
                          ],
                          "reported_state": "running",
                          "agent_status": "online",
                          "reported_state_changed_at": "2026-11-04T09:00:00Z",
                          "collection_status": "behind",
                          "stuck_reason": null,
                          "last_data_at": "2026-11-10T14:00:00Z",
                          "last_heartbeat_at": "2026-11-10T15:00:00Z",
                          "host_class": "workstation",
                          "reported_hostname": "wb-pc-04",
                          "rmm_device_id": null,
                          "psa_device_id": null,
                          "agent_version": "1.14.4",
                          "os_family": "windows",
                          "os_version": "10.0.19045",
                          "created_at": "2026-11-04T09:00:00Z",
                          "updated_at": "2026-11-10T15:00:00Z",
                          "deleted_at": null,
                          "organization_deleted_at": null
                        }
                      ],
                      "as_of": "2026-11-10T15:05:00Z",
                      "message": "agents retrieved",
                      "next_cursor": null
                    }
                  },
                  "not-online": {
                    "summary": "List the agents that are not online",
                    "value": {
                      "agents": [
                        {
                          "id": "a9e70000-0000-4000-8000-000000000203",
                          "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                          "name": "PD-EXAM-03",
                          "organization_id": "0a9e0000-0000-4000-8000-000000000105",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000105",
                            "a9e70000-0000-4000-8000-000000000203"
                          ],
                          "reported_state": "stopped",
                          "agent_status": "stopped",
                          "reported_state_changed_at": "2026-11-09T18:00:00Z",
                          "collection_status": "unknown",
                          "stuck_reason": null,
                          "last_data_at": "2026-11-09T18:00:00Z",
                          "last_heartbeat_at": "2026-11-09T18:00:00Z",
                          "host_class": "workstation",
                          "reported_hostname": "pd-exam-03",
                          "rmm_device_id": null,
                          "psa_device_id": null,
                          "agent_version": "1.14.3",
                          "os_family": "windows",
                          "os_version": "10.0.22631",
                          "created_at": "2026-11-05T08:00:00Z",
                          "updated_at": "2026-11-09T18:00:00Z",
                          "deleted_at": null,
                          "organization_deleted_at": null
                        }
                      ],
                      "as_of": "2026-11-10T15:05:00Z",
                      "message": "agents retrieved",
                      "next_cursor": null
                    }
                  },
                  "collection-attention": {
                    "summary": "List the agents whose collection is not healthy, with what a dashboard shows of each",
                    "value": {
                      "agents": [
                        {
                          "id": "a9e70000-0000-4000-8000-000000000203",
                          "organization_id": "0a9e0000-0000-4000-8000-000000000105",
                          "agent_status": "stopped",
                          "collection_status": "unknown",
                          "stuck_reason": null,
                          "last_data_at": "2026-11-09T18:00:00Z",
                          "last_heartbeat_at": "2026-11-09T18:00:00Z",
                          "reported_hostname": "pd-exam-03",
                          "rmm_device_id": null,
                          "collection_detail": null
                        },
                        {
                          "id": "a9e70000-0000-4000-8000-000000000202",
                          "organization_id": "0a9e0000-0000-4000-8000-000000000103",
                          "agent_status": "online",
                          "collection_status": "behind",
                          "stuck_reason": null,
                          "last_data_at": "2026-11-10T14:00:00Z",
                          "last_heartbeat_at": "2026-11-10T15:00:00Z",
                          "reported_hostname": "wb-pc-04",
                          "rmm_device_id": null,
                          "collection_detail": null
                        }
                      ],
                      "as_of": "2026-11-10T15:05:00Z",
                      "message": "agents retrieved",
                      "next_cursor": null
                    }
                  },
                  "every-agent": {
                    "summary": "List every agent, a thousand a page",
                    "value": {
                      "agents": [
                        {
                          "id": "a9e70000-0000-4000-8000-000000000203",
                          "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                          "name": "PD-EXAM-03",
                          "organization_id": "0a9e0000-0000-4000-8000-000000000105",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000105",
                            "a9e70000-0000-4000-8000-000000000203"
                          ],
                          "reported_state": "stopped",
                          "agent_status": "stopped",
                          "reported_state_changed_at": "2026-11-09T18:00:00Z",
                          "collection_status": "unknown",
                          "stuck_reason": null,
                          "last_data_at": "2026-11-09T18:00:00Z",
                          "last_heartbeat_at": "2026-11-09T18:00:00Z",
                          "host_class": "workstation",
                          "reported_hostname": "pd-exam-03",
                          "rmm_device_id": null,
                          "psa_device_id": null,
                          "agent_version": "1.14.3",
                          "os_family": "windows",
                          "os_version": "10.0.22631",
                          "created_at": "2026-11-05T08:00:00Z",
                          "updated_at": "2026-11-09T18:00:00Z",
                          "deleted_at": null,
                          "organization_deleted_at": null
                        },
                        {
                          "id": "a9e70000-0000-4000-8000-000000000201",
                          "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                          "name": "FIN-LT-04",
                          "organization_id": "0a9e0000-0000-4000-8000-000000000102",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000101",
                            "0a9e0000-0000-4000-8000-000000000102",
                            "a9e70000-0000-4000-8000-000000000201"
                          ],
                          "reported_state": "running",
                          "agent_status": "online",
                          "reported_state_changed_at": "2026-11-03T12:00:00Z",
                          "collection_status": "healthy",
                          "stuck_reason": null,
                          "last_data_at": "2026-11-10T15:00:00Z",
                          "last_heartbeat_at": "2026-11-10T15:00:00Z",
                          "host_class": "workstation",
                          "reported_hostname": "fin-lt-04",
                          "rmm_device_id": null,
                          "psa_device_id": null,
                          "agent_version": "1.14.4",
                          "os_family": "windows",
                          "os_version": "10.0.22631",
                          "created_at": "2026-11-03T12:00:00Z",
                          "updated_at": "2026-11-10T15:00:00Z",
                          "deleted_at": null,
                          "organization_deleted_at": null
                        },
                        {
                          "id": "a9e70000-0000-4000-8000-000000000202",
                          "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                          "name": "wb-pc-04",
                          "organization_id": "0a9e0000-0000-4000-8000-000000000103",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000103",
                            "a9e70000-0000-4000-8000-000000000202"
                          ],
                          "reported_state": "running",
                          "agent_status": "online",
                          "reported_state_changed_at": "2026-11-04T09:00:00Z",
                          "collection_status": "behind",
                          "stuck_reason": null,
                          "last_data_at": "2026-11-10T14:00:00Z",
                          "last_heartbeat_at": "2026-11-10T15:00:00Z",
                          "host_class": "workstation",
                          "reported_hostname": "wb-pc-04",
                          "rmm_device_id": null,
                          "psa_device_id": null,
                          "agent_version": "1.14.4",
                          "os_family": "windows",
                          "os_version": "10.0.19045",
                          "created_at": "2026-11-04T09:00:00Z",
                          "updated_at": "2026-11-10T15:00:00Z",
                          "deleted_at": null,
                          "organization_deleted_at": null
                        }
                      ],
                      "as_of": "2026-11-10T15:05:00Z",
                      "message": "agents retrieved",
                      "next_cursor": null
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, one given twice, or `fields` naming a field it does not have.\n`APP_API_ERR_BAD_PARAMETERS`: A filter's value is empty, names an empty item, is not one of the values the filter takes, or is not an id or a time where the filter asks for one; `parameter` names the filter.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `organization_id` is not a UUID, `subtree` is neither `true` nor `false` or comes without `organization_id`, `deleted` is not a value it takes, or `limit` is out of range, or `cursor` cannot be read or was sent with other filters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `organization.read` and `agent.read`. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "call-limit": {
                    "summary": "A token over its call limit",
                    "value": {
                      "cause": "call_limit",
                      "error": "too many requests with this API token; wait and try again",
                      "error_code": "APP_API_ERR_TOO_MANY_REQUESTS"
                    }
                  },
                  "address-limit": {
                    "summary": "A call from an address that sent too many tokens that are not valid",
                    "value": {
                      "cause": "invalid_token_attempts",
                      "error": "too many API tokens that are not valid were sent from this address; check the tokens it sends",
                      "error_code": "APP_API_ERR_TOO_MANY_REQUESTS"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/agents/summary": {
      "get": {
        "operationId": "readAgentSummary",
        "tags": [
          "agents"
        ],
        "summary": "Count agents",
        "description": "Returns how many SparkLogs Agents you can see are enrolled, active since `active_since` and inactive, and how many read each `agent_status` and report each `collection_status`, worked out at one moment. It reports on the agents, and says nothing of the devices' own health, such as disk, CPU or patches. To list the agents behind a count, list the agents. Counting an agent takes `organization.read` and `agent.read` at its organization; a count never includes an agent you cannot see, and holding both nowhere together returns 403. Narrow it to an organization, with or without the organizations below it; a deleted one returns 400, since only live organizations are counted, and one you cannot see returns 404.\n\nAccess: Needs `agent.read`. `agent.read` applies at each organization a grant covers and every organization below it. `agent.read` also admits reading ingest keys, but never their secrets.\n\nFields sent by default: as_of, active_since, inactive_before, enrolled, active, inactive, by_agent_status, by_collection_status.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": [
              "workspace:read"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "agent.read"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "summary": {
                "summary": "Count the agents you can see",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "organization_id",
            "in": "query",
            "description": "Only the agents of this organization.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "subtree",
            "in": "query",
            "description": "`true` adds the agents of every organization below `organization_id`. `true` and `false` are the only values it takes.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "active_since",
            "in": "query",
            "description": "Where the active count starts (RFC 3339), such as the start of the period a dashboard shows. 14 days before `as_of` by default.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "description": "Comma-separated top-level fields of each object to return instead of the default set.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false
          }
        ],
        "responses": {
          "200": {
            "description": "Count agents",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent_summary": {
                      "$ref": "#/components/schemas/AgentSummary",
                      "description": "The agent summary."
                    },
                    "message": {
                      "type": "string",
                      "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
                    }
                  },
                  "required": [
                    "agent_summary",
                    "message"
                  ]
                },
                "examples": {
                  "summary": {
                    "summary": "Count the agents you can see",
                    "value": {
                      "agent_summary": {
                        "as_of": "2026-11-10T15:00:00Z",
                        "active_since": "2026-10-27T15:00:00Z",
                        "inactive_before": "2026-10-27T15:00:00Z",
                        "enrolled": 3,
                        "active": 3,
                        "inactive": 0,
                        "by_agent_status": {
                          "online": 2,
                          "offline": 0,
                          "never_seen": 0,
                          "stopped": 1,
                          "system_shutdown": 0,
                          "uninstalled": 0,
                          "upgrading_overdue": 0
                        },
                        "by_collection_status": {
                          "healthy": 1,
                          "behind": 1,
                          "onboarding": 0,
                          "degraded": 0,
                          "unknown": 1,
                          "none": 0
                        }
                      },
                      "message": "summary retrieved"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, one given twice, or `fields` naming a field it does not have.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `organization_id` is not a UUID or names a deleted organization, `subtree` is neither `true` nor `false` or comes without it, or `active_since` is not a valid time.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `organization.read` and `agent.read` together at any organization. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`APP_API_ERR_RECORD_NOT_FOUND`: `organization_id` names an organization you cannot see.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/agents/{id}": {
      "patch": {
        "operationId": "updateAgent",
        "tags": [
          "agents"
        ],
        "summary": "Update an agent",
        "description": "Changes a SparkLogs Agent's name, description, device ids or custom fields; a field left out keeps its value. The name follows the machine's host name until someone sets a different name; to make it follow again, set it to the current `reported_hostname`, in any case. To label an agent and keep its name following, set `description`. Needs `agent.write` at its organization.\n\nAccess: Needs `agent.write`. `agent.write` applies at each organization a grant covers and every organization below it. `agent.write` also admits changing and moving ingest keys.\n\nUnknown input: An unknown or repeated query parameter returns 400. An unknown body field returns 400.",
        "security": [
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "agent.write"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "rename": {
                "summary": "Rename an agent",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The agent's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "rename": {
                "summary": "Rename an agent",
                "value": "a9e70000-0000-4000-8000-000000000202"
              }
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentUpdate"
              },
              "examples": {
                "rename": {
                  "summary": "Rename an agent",
                  "value": {
                    "name": "WB-PC-04 front desk"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update an agent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IDResult"
                },
                "examples": {
                  "rename": {
                    "summary": "Rename an agent",
                    "value": {
                      "message": "agent updated",
                      "id": "a9e70000-0000-4000-8000-000000000202"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`.\n`APP_API_ERR_BAD_PARAMETERS`: `name` is empty.\n`APP_API_ERR_PARAMETER_TOO_LONG`: `name` is longer than 128 characters, or `description` longer than 2048.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: The agent does not exist, is in another workspace or is outside your reach, `id` names an ingest key, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteAgent",
        "tags": [
          "agents"
        ],
        "summary": "Delete an agent",
        "description": "Marks a SparkLogs Agent deleted; its machine is refused from then on, and `cache_clear_status` says whether every region refuses it. The query parameter `uninstall` says when the machine removes the install: on that date the agent removes itself, with its local state when `uninstall_purge` is true, and left out the date is 60 days after the first delete. The options are query parameters because some HTTP clients and proxies drop or refuse a body on DELETE, which would delete the agent without scheduling its removal; a body is refused. Needs `agent.delete` at its organization. Deleting a deleted agent changes nothing, except that a named `uninstall` replaces the stored schedule. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 2 hours.\n\nAccess: Needs `agent.delete`. `agent.delete` applies at each organization a grant covers and every organization below it. `agent.delete` also admits deleting and restoring ingest keys.\n\nUnknown input: An unknown or repeated query parameter returns 400. A delete takes no body: its options are query parameters, and a body carrying anything returns 400.",
        "security": [
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "agent.delete"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "uninstall": {
                "summary": "Delete an agent and remove its install in 7 days",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "offboard": {
                "summary": "Delete a client's agent and remove its install in 7 days",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "purge-now": {
                "summary": "Delete an agent and remove its install and local state at once",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The agent's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "uninstall": {
                "summary": "Delete an agent and remove its install in 7 days",
                "value": "a9e70000-0000-4000-8000-000000000203"
              },
              "offboard": {
                "summary": "Delete a client's agent and remove its install in 7 days",
                "value": "a9e70000-0000-4000-8000-000000000201"
              },
              "purge-now": {
                "summary": "Delete an agent and remove its install and local state at once",
                "value": "a9e70000-0000-4000-8000-000000000202"
              }
            }
          },
          {
            "name": "uninstall",
            "in": "query",
            "description": "When the agent's machine removes the install. Left out, a first delete records the default of 60 days and a repeated one keeps what is stored; given on a repeated delete, it replaces the stored schedule.",
            "schema": {
              "type": "string",
              "enum": [
                "after_days",
                "immediately",
                "never"
              ]
            },
            "examples": {
              "uninstall": {
                "summary": "Delete an agent and remove its install in 7 days",
                "value": "after_days"
              },
              "offboard": {
                "summary": "Delete a client's agent and remove its install in 7 days",
                "value": "after_days"
              },
              "purge-now": {
                "summary": "Delete an agent and remove its install and local state at once",
                "value": "immediately"
              }
            }
          },
          {
            "name": "uninstall_days",
            "in": "query",
            "description": "With `after_days`, how many days after the delete: 1 to 365, 60 by default.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 365,
              "default": 60
            },
            "examples": {
              "uninstall": {
                "summary": "Delete an agent and remove its install in 7 days",
                "value": 7
              },
              "offboard": {
                "summary": "Delete a client's agent and remove its install in 7 days",
                "value": 7
              }
            }
          },
          {
            "name": "uninstall_purge",
            "in": "query",
            "description": "`true` also deletes what the agent keeps on the machine: its settings, its identity, the events it buffered and not yet sent, and its logs. Left out, they stay, and installing the agent there again later carries on from them. `true` and `false` are the only values it takes.",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "examples": {
              "purge-now": {
                "summary": "Delete an agent and remove its install and local state at once",
                "value": true
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Delete an agent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WriteResult"
                },
                "examples": {
                  "uninstall": {
                    "summary": "Delete an agent and remove its install in 7 days",
                    "value": {
                      "message": "agent deleted",
                      "cache_clear_status": "ok"
                    }
                  },
                  "offboard": {
                    "summary": "Delete a client's agent and remove its install in 7 days",
                    "value": {
                      "message": "agent deleted",
                      "cache_clear_status": "ok"
                    }
                  },
                  "purge-now": {
                    "summary": "Delete an agent and remove its install and local state at once",
                    "value": {
                      "message": "agent deleted",
                      "cache_clear_status": "ok"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, or one given twice.\n`APP_API_ERR_BAD_PARAMETERS`: `uninstall` is not one of the values it takes, `uninstall_days` is not a whole number from 1 to 365 or comes with `uninstall` other than `after_days`, `uninstall_purge` is not `true` or `false` or comes with `uninstall` `never`, or `uninstall_days` or `uninstall_purge` comes without `uninstall`; `parameter` names the parameter.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The request carries a body other than nothing, `null` or `{}`: a delete takes none, and its options are query parameters; `parameter` names the body's first field, or `body`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: The agent does not exist, is in another workspace or is outside your reach, `id` names an ingest key, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "readAgent",
        "tags": [
          "agents"
        ],
        "summary": "Read an agent",
        "description": "Returns one SparkLogs Agent you can see, deleted or not, with every field but `collection_detail`, `rollout_seed`, `host_metadata`, `agent_data` and `custom_fields` unless `fields` names them. One you cannot see returns 404, as one that does not exist does, and so does the id of an ingest key.\n\nAccess: Needs `agent.read`. `agent.read` applies at each organization a grant covers and every organization below it. `agent.read` also admits reading ingest keys, but never their secrets.\n\nFields sent by default: id, workspace_id, name, organization_id, path, reported_state, agent_status, reported_state_changed_at, collection_status, stuck_reason, last_data_at, last_heartbeat_at, host_class, reported_hostname, rmm_device_id, psa_device_id, agent_version, os_family, os_version, created_at, updated_at, deleted_at, organization_deleted_at, description, collection_feeds, update_status, update_failure_reason, install_id, synthetic_install_id, arch, host_roles, registration_token_id, cloned_from_agent_id, feed_pack_version, last_meta_at, deletion. Sent only when named: collection_detail, rollout_seed. Heavy, sent only when named: custom_fields, host_metadata, agent_data.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": [
              "workspace:read"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "agent.read"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "read": {
                "summary": "Read an agent",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "behind": {
                "summary": "Read an agent whose collection is behind",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "ingest-key-id": {
                "summary": "The id of an ingest key",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The agent's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "read": {
                "summary": "Read an agent",
                "value": "a9e70000-0000-4000-8000-000000000201"
              },
              "behind": {
                "summary": "Read an agent whose collection is behind",
                "value": "a9e70000-0000-4000-8000-000000000202"
              },
              "ingest-key-id": {
                "summary": "The id of an ingest key",
                "value": "a9e70000-0000-4000-8000-000000000204"
              }
            }
          },
          {
            "name": "fields",
            "in": "query",
            "description": "Comma-separated top-level fields of each object to return instead of the default set.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false
          }
        ],
        "responses": {
          "200": {
            "description": "Read an agent",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "agent": {
                      "$ref": "#/components/schemas/Agent",
                      "description": "The agent."
                    },
                    "message": {
                      "type": "string",
                      "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
                    }
                  },
                  "required": [
                    "agent",
                    "message"
                  ]
                },
                "examples": {
                  "read": {
                    "summary": "Read an agent",
                    "value": {
                      "agent": {
                        "id": "a9e70000-0000-4000-8000-000000000201",
                        "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                        "name": "FIN-LT-04",
                        "organization_id": "0a9e0000-0000-4000-8000-000000000102",
                        "path": [
                          "0a9e0000-0000-4000-8000-000000000100",
                          "0a9e0000-0000-4000-8000-000000000101",
                          "0a9e0000-0000-4000-8000-000000000102",
                          "a9e70000-0000-4000-8000-000000000201"
                        ],
                        "reported_state": "running",
                        "agent_status": "online",
                        "reported_state_changed_at": "2026-11-03T12:00:00Z",
                        "collection_status": "healthy",
                        "stuck_reason": null,
                        "last_data_at": "2026-11-10T15:00:00Z",
                        "last_heartbeat_at": "2026-11-10T15:00:00Z",
                        "host_class": "workstation",
                        "reported_hostname": "fin-lt-04",
                        "rmm_device_id": null,
                        "psa_device_id": null,
                        "agent_version": "1.14.4",
                        "os_family": "windows",
                        "os_version": "10.0.22631",
                        "created_at": "2026-11-03T12:00:00Z",
                        "updated_at": "2026-11-10T15:00:00Z",
                        "deleted_at": null,
                        "organization_deleted_at": null,
                        "description": null,
                        "collection_feeds": null,
                        "update_status": null,
                        "update_failure_reason": null,
                        "install_id": null,
                        "synthetic_install_id": null,
                        "arch": null,
                        "host_roles": null,
                        "registration_token_id": null,
                        "cloned_from_agent_id": null,
                        "feed_pack_version": null,
                        "last_meta_at": null,
                        "deletion": null
                      },
                      "message": "agent retrieved"
                    }
                  },
                  "behind": {
                    "summary": "Read an agent whose collection is behind",
                    "value": {
                      "agent": {
                        "id": "a9e70000-0000-4000-8000-000000000202",
                        "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                        "name": "wb-pc-04",
                        "organization_id": "0a9e0000-0000-4000-8000-000000000103",
                        "path": [
                          "0a9e0000-0000-4000-8000-000000000100",
                          "0a9e0000-0000-4000-8000-000000000103",
                          "a9e70000-0000-4000-8000-000000000202"
                        ],
                        "reported_state": "running",
                        "agent_status": "online",
                        "reported_state_changed_at": "2026-11-04T09:00:00Z",
                        "collection_status": "behind",
                        "stuck_reason": null,
                        "last_data_at": "2026-11-10T14:00:00Z",
                        "last_heartbeat_at": "2026-11-10T15:00:00Z",
                        "host_class": "workstation",
                        "reported_hostname": "wb-pc-04",
                        "rmm_device_id": null,
                        "psa_device_id": null,
                        "agent_version": "1.14.4",
                        "os_family": "windows",
                        "os_version": "10.0.19045",
                        "created_at": "2026-11-04T09:00:00Z",
                        "updated_at": "2026-11-10T15:00:00Z",
                        "deleted_at": null,
                        "organization_deleted_at": null,
                        "description": null,
                        "collection_feeds": null,
                        "update_status": null,
                        "update_failure_reason": null,
                        "install_id": null,
                        "synthetic_install_id": null,
                        "arch": null,
                        "host_roles": null,
                        "registration_token_id": null,
                        "cloned_from_agent_id": null,
                        "feed_pack_version": null,
                        "last_meta_at": null,
                        "deletion": null
                      },
                      "message": "agent retrieved"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, one given twice, or `fields` naming a field it does not have.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `organization.read` and `agent.read`. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`APP_API_ERR_RECORD_NOT_FOUND`: No such agent, or one you cannot see; an ingest key's id answers this too.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "ingest-key-id": {
                    "summary": "The id of an ingest key",
                    "value": {
                      "error": "agent not found in this workspace",
                      "error_code": "APP_API_ERR_RECORD_NOT_FOUND",
                      "parameter": "id"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/agents/{id}/move": {
      "post": {
        "operationId": "moveAgent",
        "tags": [
          "agents"
        ],
        "summary": "Move an agent",
        "description": "Moves a SparkLogs Agent to another organization. Needs `agent.write` at its organization and `ingest_key.create` at the new one. Another live agent there with the same install id returns 409. Moving it where it already is changes nothing. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 2 hours.\n\nAccess: Needs `agent.write` at the organization it is in now and `ingest_key.create` at the organization it moves to. `agent.write` applies at each organization a grant covers and every organization below it. `agent.write` also admits changing and moving ingest keys. `ingest_key.create` applies at each organization a grant covers and every organization below it. `ingest_key.create` also admits moving a SparkLogs Agent or an ingest key into an organization, with `agent.write` at the one it leaves.\n\nUnknown input: An unknown or repeated query parameter returns 400. An unknown body field returns 400.",
        "security": [
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "agent.write",
          "ingest_key.create"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "move": {
                "summary": "Move an agent to Lakeside Clinic",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The agent's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "move": {
                "summary": "Move an agent to Lakeside Clinic",
                "value": "a9e70000-0000-4000-8000-000000000202"
              }
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentMove"
              },
              "examples": {
                "move": {
                  "summary": "Move an agent to Lakeside Clinic",
                  "value": {
                    "organization_id": "0a9e0000-0000-4000-8000-000000000101"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Move an agent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WriteResult"
                },
                "examples": {
                  "move": {
                    "summary": "Move an agent to Lakeside Clinic",
                    "value": {
                      "message": "agent moved",
                      "cache_clear_status": "ok"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`.\n`APP_API_ERR_MISSING_PARAMETER`: `organization_id` is left out.\n`APP_API_ERR_BAD_PARAMETERS`: `organization_id` is not a UUID, or names a deleted organization for a live agent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: The agent or the new organization does not exist or is outside your reach, `id` names an ingest key, or you do not hold `agent.write` at the agent's organization and `ingest_key.create` at the new one. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`APP_API_ERR_ALREADY_TAKEN`: Another live agent in the new organization carries the agent's machine install id; `parameter` is `install_id`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/agents/{id}/restore": {
      "post": {
        "operationId": "restoreAgent",
        "tags": [
          "agents"
        ],
        "summary": "Restore a deleted agent",
        "description": "Restores a deleted SparkLogs Agent. It cancels a pending uninstall; an agent already removed from its machine is not reinstalled. Another live agent in its organization with the same install id returns 409. Needs `agent.delete` at its organization. Restoring a live agent changes nothing. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 2 hours.\n\nAccess: Needs `agent.delete`. `agent.delete` applies at each organization a grant covers and every organization below it. `agent.delete` also admits deleting and restoring ingest keys.\n\nUnknown input: An unknown or repeated query parameter returns 400. It takes no body: a body field returns 400.",
        "security": [
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "agent.delete"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "restore": {
                "summary": "Restore a deleted agent",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "install-id-taken": {
                "summary": "An agent whose machine enrolled again while it was deleted",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The agent's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "restore": {
                "summary": "Restore a deleted agent",
                "value": "a9e70000-0000-4000-8000-000000000203"
              },
              "install-id-taken": {
                "summary": "An agent whose machine enrolled again while it was deleted",
                "value": "a9e70000-0000-4000-8000-000000000203"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Restore a deleted agent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WriteResult"
                },
                "examples": {
                  "restore": {
                    "summary": "Restore a deleted agent",
                    "value": {
                      "message": "agent restored",
                      "cache_clear_status": "ok"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, or names a field: the call takes none.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: The agent does not exist, is in another workspace or is outside your reach, `id` names an ingest key, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`APP_API_ERR_CANNOT_RESTORE_PARENT_DELETED`: Its organization is deleted.\n`APP_API_ERR_ALREADY_TAKEN`: Another live agent in its organization carries its machine's install id; `parameter` is `install_id`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "install-id-taken": {
                    "summary": "An agent whose machine enrolled again while it was deleted",
                    "value": {
                      "error": "another live agent record for the same machine identity already exists in that organization",
                      "error_code": "APP_API_ERR_ALREADY_TAKEN",
                      "parameter": "install_id"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/audit-events": {
      "get": {
        "operationId": "listAuditEvents",
        "tags": [
          "audit-events"
        ],
        "summary": "List audit events",
        "description": "Returns the workspace's audit log a page at a time, newest first, filtered by actor, credential, organization, target, action, outcome and time; filters combine, a row passing every one given. Needs `auditlog.query`. Held over every organization, it shows every event. Held at some organizations, it shows a change when one of its organizations is inside them, a data read when one of its organizations is inside them or above them, or it covers every organization, and no event that names no organization, such as a change to the workspace itself; organizations you cannot see are left out of each event shown. Pages follow with `cursor`, as on every list.\n\nAccess: Needs `auditlog.query`. `auditlog.query` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": [
              "admin:read"
            ]
          },
          {
            "bearer": [
              "admin:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "auditlog.query"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "by-token": {
                "summary": "List what a workspace token did in the last 30 days",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "by-token-next-page": {
                "summary": "Read the next page of what a workspace token did",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "member-removed": {
                "summary": "List the removals of members",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "member-removal": {
                "summary": "List what was done to Sam, as a removal records it",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "actor_id",
            "in": "query",
            "description": "Only events done by this actor: a user id, or a workspace token's id.",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "kind": "eq",
              "clock": false,
              "with_updated_since": false
            }
          },
          {
            "name": "credential_id",
            "in": "query",
            "description": "Only events done with this API token: what one token did, and so what it created.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "x-filter": {
              "kind": "eq",
              "clock": false,
              "with_updated_since": false
            },
            "examples": {
              "by-token": {
                "summary": "List what a workspace token did in the last 30 days",
                "value": "4b1d0000-0000-4000-8000-000000000801"
              },
              "by-token-next-page": {
                "summary": "Read the next page of what a workspace token did",
                "value": "4b1d0000-0000-4000-8000-000000000801"
              }
            }
          },
          {
            "name": "organization_id",
            "in": "query",
            "description": "Only events touching this organization.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "target_id",
            "in": "query",
            "description": "Only events done to this thing, such as one agent, group or member: what happened to it. An event whose target you are not shown never matches.",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "kind": "eq",
              "clock": false,
              "with_updated_since": false
            },
            "examples": {
              "member-removal": {
                "summary": "List what was done to Sam, as a removal records it",
                "value": "SamChenExampleUserId00000002"
              }
            }
          },
          {
            "name": "action",
            "in": "query",
            "description": "Only events of these actions, such as `member.remove`. Each operation states the action it is recorded under as `audit_action`. A SparkLogs Agent changed before the `agent.` actions existed is recorded under the `ingest_key.` ones. A restore recorded before the `.restore` actions reached the workspace's region is under `<kind>.undelete`. A comma-separated list matches any of its values, each exactly and ignoring case.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false,
            "x-filter": {
              "kind": "in_fold",
              "clock": false,
              "with_updated_since": false
            },
            "examples": {
              "member-removed": {
                "summary": "List the removals of members",
                "value": [
                  "member.remove"
                ]
              },
              "member-removal": {
                "summary": "List what was done to Sam, as a removal records it",
                "value": [
                  "member.remove"
                ]
              }
            }
          },
          {
            "name": "action_prefix",
            "in": "query",
            "description": "Only events whose action starts with this, ignoring case, such as `organization.`.",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "kind": "prefix",
              "clock": false,
              "with_updated_since": false
            }
          },
          {
            "name": "outcome",
            "in": "query",
            "description": "Only events with one of these outcomes. A comma-separated list matches any of its values.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "allowed",
                  "denied",
                  "failed"
                ]
              }
            },
            "style": "form",
            "explode": false,
            "x-filter": {
              "kind": "in",
              "clock": false,
              "with_updated_since": false
            }
          },
          {
            "name": "invocation_method",
            "in": "query",
            "description": "Only events whose call reached SparkLogs one of these ways. A comma-separated list matches any of its values.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "direct",
                  "mcp"
                ]
              }
            },
            "style": "form",
            "explode": false,
            "x-filter": {
              "kind": "in",
              "clock": false,
              "with_updated_since": false
            }
          },
          {
            "name": "occurred_since",
            "in": "query",
            "description": "Only events at or after this time. An RFC 3339 time.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "x-filter": {
              "kind": "since",
              "clock": false,
              "with_updated_since": false
            },
            "examples": {
              "by-token": {
                "summary": "List what a workspace token did in the last 30 days",
                "value": "2026-10-11T00:00:00Z"
              },
              "by-token-next-page": {
                "summary": "Read the next page of what a workspace token did",
                "value": "2026-10-11T00:00:00Z"
              }
            }
          },
          {
            "name": "occurred_before",
            "in": "query",
            "description": "Only events before this time. An RFC 3339 time.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "x-filter": {
              "kind": "before",
              "clock": false,
              "with_updated_since": false
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "The `next_cursor` of the previous page, sent with the same filters: the page after it.",
            "schema": {
              "type": "string"
            },
            "examples": {
              "by-token-next-page": {
                "summary": "Read the next page of what a workspace token did",
                "value": "eyJ2IjoxLCJleGFtcGxlIjoiYXVkaXQifQ"
              }
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "How many events a page holds: 1 to 5000, 500 by default. It may change between pages.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 5000,
              "default": 500
            },
            "examples": {
              "by-token": {
                "summary": "List what a workspace token did in the last 30 days",
                "value": 1
              },
              "by-token-next-page": {
                "summary": "Read the next page of what a workspace token did",
                "value": 1
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List audit events",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditEventPage"
                },
                "examples": {
                  "by-token": {
                    "summary": "List what a workspace token did in the last 30 days",
                    "value": {
                      "message": "audit events retrieved",
                      "audit_events": [
                        {
                          "id": "ad170000-0000-4000-8000-000000000701",
                          "occurred_at": "2026-11-09T16:00:00Z",
                          "last_occurred_at": "2026-11-09T16:00:00Z",
                          "occurrences": 1,
                          "actor_kind": "workspace_key",
                          "actor_id": "4b1d0000-0000-4000-8000-000000000801",
                          "actor_desc": null,
                          "credential_kind": "workspace_key",
                          "credential_id": "4b1d0000-0000-4000-8000-000000000801",
                          "action": "organization.update",
                          "privileges": [
                            "organization.write"
                          ],
                          "target_kind": "organization",
                          "target_id": "0a9e0000-0000-4000-8000-000000000105",
                          "target_desc": "Harbor Dental",
                          "org_ids": [
                            "0a9e0000-0000-4000-8000-000000000105"
                          ],
                          "all_orgs": false,
                          "outcome": "allowed",
                          "reason": null,
                          "details": {
                            "changes": [
                              {
                                "field": "psa_client_id",
                                "new": "10057",
                                "old": null
                              }
                            ]
                          },
                          "details_v": 1,
                          "ip": "203.0.113.24",
                          "user_agent": "psa-sync/2.3",
                          "invocation_method": "direct"
                        }
                      ],
                      "next_cursor": "eyJ2IjoxLCJleGFtcGxlIjoiYXVkaXQifQ"
                    }
                  },
                  "by-token-next-page": {
                    "summary": "Read the next page of what a workspace token did",
                    "value": {
                      "message": "audit events retrieved",
                      "audit_events": [
                        {
                          "id": "ad170000-0000-4000-8000-000000000702",
                          "occurred_at": "2026-11-03T10:00:00Z",
                          "last_occurred_at": "2026-11-03T10:00:00Z",
                          "occurrences": 1,
                          "actor_kind": "workspace_key",
                          "actor_id": "4b1d0000-0000-4000-8000-000000000801",
                          "actor_desc": null,
                          "credential_kind": "workspace_key",
                          "credential_id": "4b1d0000-0000-4000-8000-000000000801",
                          "action": "organization.create",
                          "privileges": [
                            "organization.create"
                          ],
                          "target_kind": "organization",
                          "target_id": "0a9e0000-0000-4000-8000-000000000102",
                          "target_desc": "Finance",
                          "org_ids": [
                            "0a9e0000-0000-4000-8000-000000000101",
                            "0a9e0000-0000-4000-8000-000000000102"
                          ],
                          "all_orgs": false,
                          "outcome": "allowed",
                          "reason": null,
                          "details": {
                            "name": "Finance",
                            "parent_id": "0a9e0000-0000-4000-8000-000000000101"
                          },
                          "details_v": 1,
                          "ip": "203.0.113.24",
                          "user_agent": "psa-sync/2.3",
                          "invocation_method": "direct"
                        }
                      ],
                      "next_cursor": null
                    }
                  },
                  "member-removed": {
                    "summary": "List the removals of members",
                    "value": {
                      "message": "audit events retrieved",
                      "audit_events": [
                        {
                          "id": "ad170000-0000-4000-8000-000000000703",
                          "occurred_at": "2026-11-10T15:00:00Z",
                          "last_occurred_at": "2026-11-10T15:00:00Z",
                          "occurrences": 1,
                          "actor_kind": "workspace_key",
                          "actor_id": "4b1d0000-0000-4000-8000-000000000805",
                          "actor_desc": null,
                          "credential_kind": "workspace_key",
                          "credential_id": "4b1d0000-0000-4000-8000-000000000805",
                          "action": "member.remove",
                          "privileges": [
                            "member.manage"
                          ],
                          "target_kind": "member",
                          "target_id": "SamChenExampleUserId00000002",
                          "target_desc": null,
                          "org_ids": [
                            "0a9e0000-0000-4000-8000-000000000101",
                            "0a9e0000-0000-4000-8000-000000000105"
                          ],
                          "all_orgs": false,
                          "outcome": "allowed",
                          "reason": null,
                          "details": {
                            "oauth_connections": 1,
                            "pending_codes": 0,
                            "personal_tokens": 1
                          },
                          "details_v": 1,
                          "ip": "203.0.113.24",
                          "user_agent": "access-sync/1.0",
                          "invocation_method": "direct"
                        }
                      ],
                      "next_cursor": null
                    }
                  },
                  "member-removal": {
                    "summary": "List what was done to Sam, as a removal records it",
                    "value": {
                      "message": "audit events retrieved",
                      "audit_events": [
                        {
                          "id": "ad170000-0000-4000-8000-000000000703",
                          "occurred_at": "2026-11-10T15:00:00Z",
                          "last_occurred_at": "2026-11-10T15:00:00Z",
                          "occurrences": 1,
                          "actor_kind": "workspace_key",
                          "actor_id": "4b1d0000-0000-4000-8000-000000000805",
                          "actor_desc": null,
                          "credential_kind": "workspace_key",
                          "credential_id": "4b1d0000-0000-4000-8000-000000000805",
                          "action": "member.remove",
                          "privileges": [
                            "member.manage"
                          ],
                          "target_kind": "member",
                          "target_id": "SamChenExampleUserId00000002",
                          "target_desc": null,
                          "org_ids": [
                            "0a9e0000-0000-4000-8000-000000000101",
                            "0a9e0000-0000-4000-8000-000000000105"
                          ],
                          "all_orgs": false,
                          "outcome": "allowed",
                          "reason": null,
                          "details": {
                            "oauth_connections": 1,
                            "pending_codes": 0,
                            "personal_tokens": 1
                          },
                          "details_v": 1,
                          "ip": "203.0.113.24",
                          "user_agent": "access-sync/1.0",
                          "invocation_method": "direct"
                        }
                      ],
                      "next_cursor": null
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, or one given twice.\n`APP_API_ERR_BAD_PARAMETERS`: A filter's value is empty, names an empty item, is not one of the values the filter takes, or is not an id or a time where the filter asks for one; `parameter` names the filter.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `limit` is not 1 to 5000, `organization_id` is not a UUID, or `cursor` cannot be read or was sent with other filters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `auditlog.query`, or it covers no organization. The same refusal comes when the path names a workspace other than the token's own.\n`APP_API_ERR_NO_PRIVILEGE`: `organization_id` names an organization outside your audit reach.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/audit-events/{id}": {
      "get": {
        "operationId": "readAuditEvent",
        "tags": [
          "audit-events"
        ],
        "summary": "Read an audit event",
        "description": "Returns one audit event as the list shows it, its lists whole. Needs `auditlog.query`. One you cannot see returns 404, as one that does not exist does.\n\nAccess: Needs `auditlog.query`. `auditlog.query` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": [
              "admin:read"
            ]
          },
          {
            "bearer": [
              "admin:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "auditlog.query"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "read": {
                "summary": "Read an audit event",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The audit event's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "read": {
                "summary": "Read an audit event",
                "value": "ad170000-0000-4000-8000-000000000701"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Read an audit event",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditEventRead"
                },
                "examples": {
                  "read": {
                    "summary": "Read an audit event",
                    "value": {
                      "message": "audit event retrieved",
                      "audit_event": {
                        "id": "ad170000-0000-4000-8000-000000000701",
                        "occurred_at": "2026-11-09T16:00:00Z",
                        "last_occurred_at": "2026-11-09T16:00:00Z",
                        "occurrences": 1,
                        "actor_kind": "workspace_key",
                        "actor_id": "4b1d0000-0000-4000-8000-000000000801",
                        "actor_desc": null,
                        "credential_kind": "workspace_key",
                        "credential_id": "4b1d0000-0000-4000-8000-000000000801",
                        "action": "organization.update",
                        "privileges": [
                          "organization.write"
                        ],
                        "target_kind": "organization",
                        "target_id": "0a9e0000-0000-4000-8000-000000000105",
                        "target_desc": "Harbor Dental",
                        "org_ids": [
                          "0a9e0000-0000-4000-8000-000000000105"
                        ],
                        "all_orgs": false,
                        "outcome": "allowed",
                        "reason": null,
                        "details": {
                          "changes": [
                            {
                              "field": "psa_client_id",
                              "new": "10057",
                              "old": null
                            }
                          ]
                        },
                        "details_v": 1,
                        "ip": "203.0.113.24",
                        "user_agent": "psa-sync/2.3",
                        "invocation_method": "direct"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, or one given twice.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `auditlog.query`. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`APP_API_ERR_RECORD_NOT_FOUND`: No such event, or one you cannot see.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/grants": {
      "post": {
        "operationId": "createGrant",
        "tags": [
          "grants"
        ],
        "summary": "Give a grant",
        "description": "Gives a member, a group or a workspace token a role over a scope. Needs `grant.write` across the scope and over everything the role reaches; a grant on a group also needs `group.write` there, and one on a workspace token `workspace_token.manage` there and `workspace_token.view` to see the token, which a token holds only with `admin:delegate`. A workspace token never changes its own grants. The grantee must sit inside your reach. A grantee you cannot see gets the same response as one that does not exist. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 15 minutes.\n\nAccess: Needs `grant.write`. `grant.write` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400. An unknown body field returns 400.",
        "security": [
          {
            "bearer": [
              "admin:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "grant.write"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "engineer-lakeside": {
                "summary": "Make Sam an engineer for Lakeside Clinic",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GrantCreate"
              },
              "examples": {
                "engineer-lakeside": {
                  "summary": "Make Sam an engineer for Lakeside Clinic",
                  "value": {
                    "grantee": {
                      "id": "SamChenExampleUserId00000002",
                      "kind": "user"
                    },
                    "role_id": "engineer",
                    "scope": {
                      "kind": "selected",
                      "org_ids": [
                        "0a9e0000-0000-4000-8000-000000000101"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Give a grant",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IDResult"
                },
                "examples": {
                  "engineer-lakeside": {
                    "summary": "Make Sam an engineer for Lakeside Clinic",
                    "value": {
                      "message": "grant created",
                      "id": "6a170000-0000-4000-8000-000000000502",
                      "cache_clear_status": "ok"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`.\n`APP_API_ERR_BAD_PARAMETERS`: `grantee` names no kind or id, or a grant names a role the workspace does not have, or a malformed scope.\n`APP_API_ERR_MISSING_PARAMETER`: The grant names no role.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `grant.write`. The same refusal comes when the path names a workspace other than the token's own.\n`APP_API_ERR_BEYOND_OWN_AUTHORITY`: The change gives or takes away access you do not hold yourself, or a workspace token would change its own grants. `cause` is `token_scope` only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`APP_API_ERR_RECORD_NOT_FOUND`: The grantee is not in the workspace, or not one you can see.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/grants/batch": {
      "post": {
        "operationId": "changeGrants",
        "tags": [
          "grants"
        ],
        "summary": "Change a grantee's grants together",
        "description": "Removes, changes and adds a grantee's direct grants in one transaction: every change is judged as the single-grant calls judge it, and any refusal writes nothing. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 15 minutes.\n\nAccess: Needs `grant.write`. `grant.write` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400. An unknown body field returns 400.",
        "security": [
          {
            "bearer": [
              "admin:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "grant.write"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "swap": {
                "summary": "Swap a group's grant for a wider one",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GrantBatch"
              },
              "examples": {
                "swap": {
                  "summary": "Swap a group's grant for a wider one",
                  "value": {
                    "add": [
                      {
                        "role_id": "analyst_no_raw_logs",
                        "scope": {
                          "kind": "all",
                          "org_ids": []
                        }
                      }
                    ],
                    "grantee": {
                      "id": "9a0b0000-0000-4000-8000-000000000401",
                      "kind": "group"
                    },
                    "remove": [
                      "6a170000-0000-4000-8000-000000000503"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Change a grantee's grants together",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GrantsChanged"
                },
                "examples": {
                  "swap": {
                    "summary": "Swap a group's grant for a wider one",
                    "value": {
                      "message": "grants changed",
                      "removed": [
                        "6a170000-0000-4000-8000-000000000503"
                      ],
                      "updated": [],
                      "added": [
                        "6a170000-0000-4000-8000-000000000505"
                      ],
                      "cache_clear_status": "ok"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`.\n`APP_API_ERR_BAD_PARAMETERS`: `grantee` is malformed, a grant id comes twice across `remove` and `update`, or a grant names a role the workspace does not have, or a malformed scope.\n`APP_API_ERR_MISSING_PARAMETER`: `remove`, `update` and `add` are all empty, or a grant names no role.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `grant.write`. The same refusal comes when the path names a workspace other than the token's own.\n`APP_API_ERR_BEYOND_OWN_AUTHORITY`: The change gives or takes away access you do not hold yourself, or a workspace token would change its own grants. `cause` is `token_scope` only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`APP_API_ERR_RECORD_NOT_FOUND`: The grantee, or a grant in `remove` or `update`, is missing, belongs to another grantee or is outside your reach; `parameter` names it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`APP_API_ERR_LAST_ADMINISTRATOR`: The change would leave no administrator over every organization. Only a signed-in session meets this: no scope carries every privilege an Administrator holds, so an API token is refused with 403 first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/grants/{id}": {
      "put": {
        "operationId": "updateGrant",
        "tags": [
          "grants"
        ],
        "summary": "Replace a grant",
        "description": "Replaces a grant's role and scope. Needs `grant.write` over both the grant as stored and as replaced, judged as giving a grant is. A grant you cannot see returns 404, as one that does not exist does. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 15 minutes.\n\nAccess: Needs `grant.write`. `grant.write` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400. An unknown body field returns 400.",
        "security": [
          {
            "bearer": [
              "admin:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "grant.write"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "widen": {
                "summary": "Extend Sam's grant to Harbor Dental",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "drop-client": {
                "summary": "Narrow the helpdesk group's grant to Harbor Dental",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The grant's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "widen": {
                "summary": "Extend Sam's grant to Harbor Dental",
                "value": "6a170000-0000-4000-8000-000000000502"
              },
              "drop-client": {
                "summary": "Narrow the helpdesk group's grant to Harbor Dental",
                "value": "6a170000-0000-4000-8000-000000000503"
              }
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GrantRequest"
              },
              "examples": {
                "widen": {
                  "summary": "Extend Sam's grant to Harbor Dental",
                  "value": {
                    "role_id": "engineer",
                    "scope": {
                      "kind": "selected",
                      "org_ids": [
                        "0a9e0000-0000-4000-8000-000000000101",
                        "0a9e0000-0000-4000-8000-000000000105"
                      ]
                    }
                  }
                },
                "drop-client": {
                  "summary": "Narrow the helpdesk group's grant to Harbor Dental",
                  "value": {
                    "role_id": "analyst_no_raw_logs",
                    "scope": {
                      "kind": "selected",
                      "org_ids": [
                        "0a9e0000-0000-4000-8000-000000000105"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Replace a grant",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IDResult"
                },
                "examples": {
                  "widen": {
                    "summary": "Extend Sam's grant to Harbor Dental",
                    "value": {
                      "message": "grant replaced",
                      "id": "6a170000-0000-4000-8000-000000000502",
                      "cache_clear_status": "ok"
                    }
                  },
                  "drop-client": {
                    "summary": "Narrow the helpdesk group's grant to Harbor Dental",
                    "value": {
                      "message": "grant replaced",
                      "id": "6a170000-0000-4000-8000-000000000503",
                      "cache_clear_status": "ok"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`.\n`APP_API_ERR_BAD_PARAMETERS`: A grant names a role the workspace does not have, or a malformed scope.\n`APP_API_ERR_MISSING_PARAMETER`: The grant names no role.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `grant.write`. The same refusal comes when the path names a workspace other than the token's own.\n`APP_API_ERR_BEYOND_OWN_AUTHORITY`: The change gives or takes away access you do not hold yourself, or a workspace token would change its own grants. `cause` is `token_scope` only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`APP_API_ERR_RECORD_NOT_FOUND`: No such grant, or one you cannot see.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`APP_API_ERR_LAST_ADMINISTRATOR`: The change would leave no administrator over every organization. Only a signed-in session meets this: no scope carries every privilege an Administrator holds, so an API token is refused with 403 first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteGrant",
        "tags": [
          "grants"
        ],
        "summary": "Remove a grant",
        "description": "Removes a grant. Needs `grant.write` over it, judged as giving it is. It removes the whole grant; to drop one organization from a `selected` grant, update it with the rest. A grant you cannot see returns 404, as one that does not exist does, and so does a repeat once it is gone: treat that as done. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 15 minutes.\n\nAccess: Needs `grant.write`. `grant.write` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400. A delete takes no body: its options are query parameters, and a body carrying anything returns 400.",
        "security": [
          {
            "bearer": [
              "admin:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "grant.write"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "remove": {
                "summary": "Remove Sam's grant",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "beyond-reach": {
                "summary": "Remove a grant that also covers an organization the token cannot see, with Organization Administrator over Lakeside Clinic alone",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The grant's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "remove": {
                "summary": "Remove Sam's grant",
                "value": "6a170000-0000-4000-8000-000000000502"
              },
              "beyond-reach": {
                "summary": "Remove a grant that also covers an organization the token cannot see, with Organization Administrator over Lakeside Clinic alone",
                "value": "6a170000-0000-4000-8000-000000000503"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Remove a grant",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WriteResult"
                },
                "examples": {
                  "remove": {
                    "summary": "Remove Sam's grant",
                    "value": {
                      "message": "grant deleted",
                      "cache_clear_status": "ok"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, or one given twice.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The request carries a body other than nothing, `null` or `{}`: a delete takes none, and its options are query parameters; `parameter` names the body's first field, or `body`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `grant.write`. The same refusal comes when the path names a workspace other than the token's own.\n`APP_API_ERR_BEYOND_OWN_AUTHORITY`: The change gives or takes away access you do not hold yourself, or a workspace token would change its own grants. `cause` is `token_scope` only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "beyond-reach": {
                    "summary": "Remove a grant that also covers an organization the token cannot see, with Organization Administrator over Lakeside Clinic alone",
                    "value": {
                      "error": "cannot grant or remove privileges or organization access beyond your own",
                      "error_code": "APP_API_ERR_BEYOND_OWN_AUTHORITY"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`APP_API_ERR_RECORD_NOT_FOUND`: No such grant, or one you cannot see.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`APP_API_ERR_LAST_ADMINISTRATOR`: The change would leave no administrator over every organization. Only a signed-in session meets this: no scope carries every privilege an Administrator holds, so an API token is refused with 403 first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/groups": {
      "get": {
        "operationId": "listGroups",
        "tags": [
          "groups"
        ],
        "summary": "List groups",
        "description": "Returns the workspace's groups, each with its grants and how many members it has, a page at a time, oldest first. Needs `group.read`; you see the groups your reach contains.\n\nAccess: Needs `group.read`. `group.read` applies at each organization a grant covers and every organization below it. A caller who reaches no organization gets an empty list.\n\nFields sent by default: id, name, created_at, updated_at, grants, other_grants, member_count. Sent only when named: members.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": [
              "admin:read"
            ]
          },
          {
            "bearer": [
              "admin:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "group.read"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "list": {
                "summary": "List groups",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "by-name": {
                "summary": "Find the group a create refused as taken",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "with-members": {
                "summary": "List groups with their grants and members",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "lakeside-admin": {
                "summary": "List groups with a token granted Organization Administrator over Lakeside Clinic alone",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "name",
            "in": "query",
            "description": "Only the group of this name: the way to find the group a refused create names as taken. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "kind": "eq_fold",
              "clock": false,
              "with_updated_since": false
            },
            "examples": {
              "by-name": {
                "summary": "Find the group a create refused as taken",
                "value": "helpdesk tier 1"
              }
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "How many groups a page holds: 1 to 5000, 1000 by default.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 5000
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "The `next_cursor` of the previous page, with the same filters.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "description": "Comma-separated top-level fields of each object to return instead of the default set.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false,
            "examples": {
              "with-members": {
                "summary": "List groups with their grants and members",
                "value": [
                  "id",
                  "name",
                  "created_at",
                  "updated_at",
                  "grants",
                  "other_grants",
                  "member_count",
                  "members"
                ]
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List groups",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "groups": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Group"
                      },
                      "description": "The groups on this page."
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Null on the last page. Otherwise pass it as `cursor` for the next page."
                    },
                    "message": {
                      "type": "string",
                      "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
                    }
                  },
                  "required": [
                    "groups",
                    "next_cursor",
                    "message"
                  ]
                },
                "examples": {
                  "list": {
                    "summary": "List groups",
                    "value": {
                      "groups": [
                        {
                          "id": "9a0b0000-0000-4000-8000-000000000401",
                          "name": "Helpdesk Tier 1",
                          "created_at": "2026-11-02T10:00:00Z",
                          "updated_at": "2026-11-02T10:00:00Z",
                          "grants": [
                            {
                              "id": "6a170000-0000-4000-8000-000000000503",
                              "role_id": "analyst_no_raw_logs",
                              "scope": {
                                "kind": "selected",
                                "org_ids": [
                                  "0a9e0000-0000-4000-8000-000000000101",
                                  "0a9e0000-0000-4000-8000-000000000105"
                                ],
                                "inherited": false,
                                "other_orgs": false
                              }
                            }
                          ],
                          "other_grants": false,
                          "member_count": 1
                        },
                        {
                          "id": "9a0b0000-0000-4000-8000-000000000402",
                          "name": "Project Engineers",
                          "created_at": "2026-11-02T10:00:00Z",
                          "updated_at": "2026-11-02T10:00:00Z",
                          "grants": [
                            {
                              "id": "6a170000-0000-4000-8000-000000000505",
                              "role_id": "engineer",
                              "scope": {
                                "kind": "selected",
                                "org_ids": [
                                  "0a9e0000-0000-4000-8000-000000000103"
                                ],
                                "inherited": false,
                                "other_orgs": false
                              }
                            }
                          ],
                          "other_grants": false,
                          "member_count": 0
                        }
                      ],
                      "message": "workspace groups retrieved",
                      "next_cursor": null
                    }
                  },
                  "by-name": {
                    "summary": "Find the group a create refused as taken",
                    "value": {
                      "groups": [
                        {
                          "id": "9a0b0000-0000-4000-8000-000000000401",
                          "name": "Helpdesk Tier 1",
                          "created_at": "2026-11-02T10:00:00Z",
                          "updated_at": "2026-11-02T10:00:00Z",
                          "grants": [
                            {
                              "id": "6a170000-0000-4000-8000-000000000503",
                              "role_id": "analyst_no_raw_logs",
                              "scope": {
                                "kind": "selected",
                                "org_ids": [
                                  "0a9e0000-0000-4000-8000-000000000101",
                                  "0a9e0000-0000-4000-8000-000000000105"
                                ],
                                "inherited": false,
                                "other_orgs": false
                              }
                            }
                          ],
                          "other_grants": false,
                          "member_count": 1
                        }
                      ],
                      "message": "workspace groups retrieved",
                      "next_cursor": null
                    }
                  },
                  "with-members": {
                    "summary": "List groups with their grants and members",
                    "value": {
                      "groups": [
                        {
                          "id": "9a0b0000-0000-4000-8000-000000000401",
                          "name": "Helpdesk Tier 1",
                          "created_at": "2026-11-02T10:00:00Z",
                          "updated_at": "2026-11-02T10:00:00Z",
                          "grants": [
                            {
                              "id": "6a170000-0000-4000-8000-000000000503",
                              "role_id": "analyst_no_raw_logs",
                              "scope": {
                                "kind": "selected",
                                "org_ids": [
                                  "0a9e0000-0000-4000-8000-000000000101",
                                  "0a9e0000-0000-4000-8000-000000000105"
                                ],
                                "inherited": false,
                                "other_orgs": false
                              }
                            }
                          ],
                          "other_grants": false,
                          "member_count": 1,
                          "members": [
                            {
                              "user_id": "SamChenExampleUserId00000002",
                              "email": "sam.chen@example.com",
                              "full_name": "Sam Chen",
                              "display_name": "Sam"
                            }
                          ]
                        },
                        {
                          "id": "9a0b0000-0000-4000-8000-000000000402",
                          "name": "Project Engineers",
                          "created_at": "2026-11-02T10:00:00Z",
                          "updated_at": "2026-11-02T10:00:00Z",
                          "grants": [
                            {
                              "id": "6a170000-0000-4000-8000-000000000505",
                              "role_id": "engineer",
                              "scope": {
                                "kind": "selected",
                                "org_ids": [
                                  "0a9e0000-0000-4000-8000-000000000103"
                                ],
                                "inherited": false,
                                "other_orgs": false
                              }
                            }
                          ],
                          "other_grants": false,
                          "member_count": 0,
                          "members": []
                        }
                      ],
                      "message": "workspace groups retrieved",
                      "next_cursor": null
                    }
                  },
                  "lakeside-admin": {
                    "summary": "List groups with a token granted Organization Administrator over Lakeside Clinic alone",
                    "value": {
                      "groups": [
                        {
                          "id": "9a0b0000-0000-4000-8000-000000000401",
                          "name": "Helpdesk Tier 1",
                          "created_at": "2026-11-02T10:00:00Z",
                          "updated_at": "2026-11-02T10:00:00Z",
                          "grants": [
                            {
                              "id": "6a170000-0000-4000-8000-000000000503",
                              "role_id": "analyst_no_raw_logs",
                              "scope": {
                                "kind": "selected",
                                "org_ids": [
                                  "0a9e0000-0000-4000-8000-000000000101"
                                ],
                                "inherited": false,
                                "other_orgs": true
                              }
                            }
                          ],
                          "other_grants": false,
                          "member_count": 1
                        }
                      ],
                      "message": "workspace groups retrieved",
                      "next_cursor": null
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, one given twice, or `fields` naming a field it does not have.\n`APP_API_ERR_BAD_PARAMETERS`: A filter's value is empty, names an empty item, is not one of the values the filter takes, or is not an id or a time where the filter asks for one; `parameter` names the filter.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `limit` is not 1 to 5000, or `cursor` cannot be read or was sent with other filters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `group.read`. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createGroup",
        "tags": [
          "groups"
        ],
        "summary": "Create a group",
        "description": "Creates a group with its grants and, optionally, its members. Needs `group.write`, and `grant.write` over each grant it names; a group with no grants needs `group.write` over every organization. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 15 minutes.\n\nAccess: Needs `group.write`. `group.write` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400. An unknown body field returns 400.",
        "security": [
          {
            "bearer": [
              "admin:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "group.write"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "helpdesk": {
                "summary": "Create the helpdesk group",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GroupCreate"
              },
              "examples": {
                "helpdesk": {
                  "summary": "Create the helpdesk group",
                  "value": {
                    "grants": [
                      {
                        "role_id": "analyst_no_raw_logs",
                        "scope": {
                          "kind": "selected",
                          "org_ids": [
                            "0a9e0000-0000-4000-8000-000000000101",
                            "0a9e0000-0000-4000-8000-000000000105"
                          ]
                        }
                      }
                    ],
                    "name": "Helpdesk Tier 1",
                    "user_ids": [
                      "SamChenExampleUserId00000002"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Create a group",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IDResult"
                },
                "examples": {
                  "helpdesk": {
                    "summary": "Create the helpdesk group",
                    "value": {
                      "message": "group created",
                      "id": "9a0b0000-0000-4000-8000-000000000401",
                      "cache_clear_status": "ok"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`.\n`APP_API_ERR_BAD_PARAMETERS`: `name` is empty, a member in `user_ids` is not one you can see, or a grant names a role the workspace does not have, or a malformed scope.\n`APP_API_ERR_MISSING_PARAMETER`: A grant names no role.\n`APP_API_ERR_PARAMETER_TOO_LONG`: `name` is longer than 128 characters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `group.write`. The same refusal comes when the path names a workspace other than the token's own.\n`APP_API_ERR_BEYOND_OWN_AUTHORITY`: A grant reaches beyond what you may grant, or the group has no grants and you do not hold `group.write` over every organization. `cause` is `token_scope` only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`APP_API_ERR_ALREADY_TAKEN`: Another group in the workspace has this name; `parameter` is `name`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/groups/{id}": {
      "get": {
        "operationId": "readGroup",
        "tags": [
          "groups"
        ],
        "summary": "Read a group",
        "description": "Returns one group with everyone in it, whatever your reach, so the membership read can be sent back whole. Needs `group.read`. A group you cannot see returns 404, as one that does not exist does.\n\nAccess: Needs `group.read`. `group.read` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": [
              "admin:read"
            ]
          },
          {
            "bearer": [
              "admin:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "group.read"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "read": {
                "summary": "Read a group with its members",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "after-add": {
                "summary": "Read the helpdesk group after adding Casey",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The group's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "read": {
                "summary": "Read a group with its members",
                "value": "9a0b0000-0000-4000-8000-000000000401"
              },
              "after-add": {
                "summary": "Read the helpdesk group after adding Casey",
                "value": "9a0b0000-0000-4000-8000-000000000401"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Read a group",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GroupRead"
                },
                "examples": {
                  "read": {
                    "summary": "Read a group with its members",
                    "value": {
                      "message": "workspace group retrieved",
                      "group": {
                        "id": "9a0b0000-0000-4000-8000-000000000401",
                        "name": "Helpdesk Tier 1",
                        "created_at": "2026-11-02T10:00:00Z",
                        "updated_at": "2026-11-02T10:00:00Z",
                        "grants": [
                          {
                            "id": "6a170000-0000-4000-8000-000000000503",
                            "role_id": "analyst_no_raw_logs",
                            "scope": {
                              "kind": "selected",
                              "org_ids": [
                                "0a9e0000-0000-4000-8000-000000000101",
                                "0a9e0000-0000-4000-8000-000000000105"
                              ],
                              "inherited": false,
                              "other_orgs": false
                            }
                          }
                        ],
                        "other_grants": false,
                        "member_count": 1,
                        "members": [
                          {
                            "user_id": "SamChenExampleUserId00000002",
                            "email": "sam.chen@example.com",
                            "full_name": "Sam Chen",
                            "display_name": "Sam"
                          }
                        ]
                      }
                    }
                  },
                  "after-add": {
                    "summary": "Read the helpdesk group after adding Casey",
                    "value": {
                      "message": "workspace group retrieved",
                      "group": {
                        "id": "9a0b0000-0000-4000-8000-000000000401",
                        "name": "Helpdesk Tier 1",
                        "created_at": "2026-11-02T10:00:00Z",
                        "updated_at": "2026-11-08T12:00:00Z",
                        "grants": [
                          {
                            "id": "6a170000-0000-4000-8000-000000000503",
                            "role_id": "analyst_no_raw_logs",
                            "scope": {
                              "kind": "selected",
                              "org_ids": [
                                "0a9e0000-0000-4000-8000-000000000101",
                                "0a9e0000-0000-4000-8000-000000000105"
                              ],
                              "inherited": false,
                              "other_orgs": false
                            }
                          }
                        ],
                        "other_grants": false,
                        "member_count": 2,
                        "members": [
                          {
                            "user_id": "SamChenExampleUserId00000002",
                            "email": "sam.chen@example.com",
                            "full_name": "Sam Chen",
                            "display_name": "Sam"
                          },
                          {
                            "user_id": "CaseyNguyenExampleUserId0003",
                            "email": "casey.nguyen@example.com",
                            "full_name": "Casey Nguyen",
                            "display_name": "Casey"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, or one given twice.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `group.read`. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`APP_API_ERR_RECORD_NOT_FOUND`: No such group, or one you cannot see.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateGroup",
        "tags": [
          "groups"
        ],
        "summary": "Rename a group",
        "description": "Renames a group. Needs `group.write` over it. A group you cannot see returns 404, as one that does not exist does.\n\nAccess: Needs `group.write`. `group.write` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400. An unknown body field returns 400.",
        "security": [
          {
            "bearer": [
              "admin:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "group.write"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "rename": {
                "summary": "Rename a group",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "name-taken": {
                "summary": "A name another group holds",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The group's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "rename": {
                "summary": "Rename a group",
                "value": "9a0b0000-0000-4000-8000-000000000402"
              },
              "name-taken": {
                "summary": "A name another group holds",
                "value": "9a0b0000-0000-4000-8000-000000000402"
              }
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GroupRename"
              },
              "examples": {
                "rename": {
                  "summary": "Rename a group",
                  "value": {
                    "name": "Field Engineers"
                  }
                },
                "name-taken": {
                  "summary": "A name another group holds",
                  "value": {
                    "name": "Helpdesk Tier 1"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rename a group",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IDResult"
                },
                "examples": {
                  "rename": {
                    "summary": "Rename a group",
                    "value": {
                      "message": "group renamed",
                      "id": "9a0b0000-0000-4000-8000-000000000402"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`.\n`APP_API_ERR_BAD_PARAMETERS`: `name` is empty.\n`APP_API_ERR_PARAMETER_TOO_LONG`: `name` is longer than 128 characters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `group.write`. The same refusal comes when the path names a workspace other than the token's own.\n`APP_API_ERR_BEYOND_OWN_AUTHORITY`: The group holds grants beyond your reach. `cause` is `token_scope` only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`APP_API_ERR_RECORD_NOT_FOUND`: No such group, or one you cannot see.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`APP_API_ERR_ALREADY_TAKEN`: Another group in the workspace has this name; `parameter` is `name`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "name-taken": {
                    "summary": "A name another group holds",
                    "value": {
                      "error": "another group in this workspace has this name",
                      "error_code": "APP_API_ERR_ALREADY_TAKEN",
                      "parameter": "name"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteGroup",
        "tags": [
          "groups"
        ],
        "summary": "Delete a group",
        "description": "Deletes a group and its grants; its members lose what they held through it. Needs `group.write`, and the group must sit inside your own access: for each of its grants, `grant.write`, `group.write` and every privilege of the grant's role across the grant's whole scope, as giving that grant would need, or 403 `APP_API_ERR_BEYOND_OWN_AUTHORITY`. `other_grants` and the `scope` markers on a read of the group show grants outside your reach, but a group can be refused without them. A group you cannot see returns 404, and so does a repeat once the group is gone: treat that as done. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 15 minutes.\n\nAccess: Needs `group.write`. `group.write` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400. A delete takes no body: its options are query parameters, and a body carrying anything returns 400.",
        "security": [
          {
            "bearer": [
              "admin:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "group.write"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "delete": {
                "summary": "Delete a group",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The group's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "delete": {
                "summary": "Delete a group",
                "value": "9a0b0000-0000-4000-8000-000000000402"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Delete a group",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WriteResult"
                },
                "examples": {
                  "delete": {
                    "summary": "Delete a group",
                    "value": {
                      "message": "group deleted",
                      "cache_clear_status": "ok"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, or one given twice.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The request carries a body other than nothing, `null` or `{}`: a delete takes none, and its options are query parameters; `parameter` names the body's first field, or `body`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `group.write`. The same refusal comes when the path names a workspace other than the token's own.\n`APP_API_ERR_BEYOND_OWN_AUTHORITY`: You do not hold `grant.write`, `group.write` and every privilege of each of the group's grants across that grant's whole scope, as giving the grant would need; a group with no grants needs `group.write` over every organization. `cause` is `token_scope` only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`APP_API_ERR_RECORD_NOT_FOUND`: No such group, or one you cannot see.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/groups/{id}/members": {
      "put": {
        "operationId": "updateGroupMembers",
        "tags": [
          "groups"
        ],
        "summary": "Set a group's members",
        "description": "Sets who is in a group: the list sent is the whole membership, so a member left out is removed. A member added must be one your member list shows. Needs `group.write`, and the group must sit inside your own access: for each of its grants, `grant.write`, `group.write` and every privilege of the grant's role across the grant's whole scope, as giving that grant would need, or 403 `APP_API_ERR_BEYOND_OWN_AUTHORITY`, even when the list sent changes nothing. `other_grants` and the `scope` markers on a read of the group show grants outside your reach, but a group can be refused without them. A group you cannot see returns 404. Sending the members it already has changes nothing. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 15 minutes.\n\nAccess: Needs `group.write`. `group.write` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400. An unknown body field returns 400.",
        "security": [
          {
            "bearer": [
              "admin:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "group.write"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "set": {
                "summary": "Add Alex to the helpdesk group, keeping Sam",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "add-member": {
                "summary": "Add Casey to the helpdesk group, keeping Sam",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The group's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "set": {
                "summary": "Add Alex to the helpdesk group, keeping Sam",
                "value": "9a0b0000-0000-4000-8000-000000000401"
              },
              "add-member": {
                "summary": "Add Casey to the helpdesk group, keeping Sam",
                "value": "9a0b0000-0000-4000-8000-000000000401"
              }
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GroupMembers"
              },
              "examples": {
                "set": {
                  "summary": "Add Alex to the helpdesk group, keeping Sam",
                  "value": {
                    "user_ids": [
                      "SamChenExampleUserId00000002",
                      "AlexRiveraExampleUserId00001"
                    ]
                  }
                },
                "add-member": {
                  "summary": "Add Casey to the helpdesk group, keeping Sam",
                  "value": {
                    "user_ids": [
                      "SamChenExampleUserId00000002",
                      "CaseyNguyenExampleUserId0003"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Set a group's members",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IDResult"
                },
                "examples": {
                  "set": {
                    "summary": "Add Alex to the helpdesk group, keeping Sam",
                    "value": {
                      "message": "group members replaced",
                      "id": "9a0b0000-0000-4000-8000-000000000401",
                      "cache_clear_status": "ok"
                    }
                  },
                  "add-member": {
                    "summary": "Add Casey to the helpdesk group, keeping Sam",
                    "value": {
                      "message": "group members replaced",
                      "id": "9a0b0000-0000-4000-8000-000000000401",
                      "cache_clear_status": "ok"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`.\n`APP_API_ERR_MISSING_PARAMETER`: `user_ids` is left out, null or not a list of strings.\n`APP_API_ERR_BAD_PARAMETERS`: A member added is not one you can see.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `group.write`. The same refusal comes when the path names a workspace other than the token's own.\n`APP_API_ERR_BEYOND_OWN_AUTHORITY`: You do not hold `grant.write`, `group.write` and every privilege of each of the group's grants across that grant's whole scope, as giving the grant would need; a group with no grants needs `group.write` over every organization. A list that changes nothing is refused the same way. `cause` is `token_scope` only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`APP_API_ERR_RECORD_NOT_FOUND`: No such group, or one you cannot see.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/ingest-keys": {
      "post": {
        "operationId": "createIngestKey",
        "tags": [
          "ingest-keys"
        ],
        "summary": "Create an ingest key",
        "description": "Creates an ingest key for `organization_id` and returns the key senders present. Needs `ingest_key.create` at that organization.\n\nAccess: Needs `ingest_key.create`. `ingest_key.create` applies at each organization a grant covers and every organization below it. `ingest_key.create` also admits moving a SparkLogs Agent or an ingest key into an organization, with `agent.write` at the one it leaves.\n\nUnknown input: An unknown or repeated query parameter returns 400. An unknown body field returns 400.\n\nSecret: The response carries a secret and is sent with `Cache-Control: no-store`. Keep it out of caches and logs.",
        "security": [
          {
            "bearer": [
              "fleet:deploy"
            ]
          },
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "ingest_key.create"
        ],
        "x-returns-secret": true,
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "harbor-servers": {
                "summary": "Create an ingest key for Harbor Dental's servers",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IngestKeyCreate"
              },
              "examples": {
                "harbor-servers": {
                  "summary": "Create an ingest key for Harbor Dental's servers",
                  "value": {
                    "name": "Harbor Dental servers",
                    "organization_id": "0a9e0000-0000-4000-8000-000000000105"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Create an ingest key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IngestKeyCreated"
                },
                "examples": {
                  "harbor-servers": {
                    "summary": "Create an ingest key for Harbor Dental's servers",
                    "value": {
                      "message": "ingest key created",
                      "id": "a9e70000-0000-4000-8000-000000000204",
                      "key": "EXAMPLE-INGEST-KEY-NOT-A-REAL-SECRET"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`.\n`APP_API_ERR_MISSING_PARAMETER`: `organization_id` or `name` is left out or empty.\n`APP_API_ERR_BAD_PARAMETERS`: `organization_id` is not a UUID or names a deleted organization.\n`APP_API_ERR_PARAMETER_TOO_LONG`: `name` is longer than 128 characters, or `description` longer than 2048.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: You do not hold `ingest_key.create` at `organization_id`, or it names no organization you can see. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listIngestKeys",
        "tags": [
          "ingest-keys"
        ],
        "summary": "List ingest keys",
        "description": "Returns the ingest keys you can see, a page at a time, in `id` order, never with their secrets. Seeing a key takes `organization.read` and `agent.read` at its organization. Filter by organization, with or without the organizations below it, by `name`, or by inactivity; filters combine, a row passing every one given. A moving `inactive_before` cutoff, such as 14 days before now, and `data_status` are worked out at the walk's `as_of`, the same instant for every page.\n\nAccess: Needs `agent.read`. `agent.read` applies at each organization a grant covers and every organization below it. `agent.read` also admits reading ingest keys, but never their secrets. A caller who reaches no organization gets an empty list.\n\nFields sent by default: id, workspace_id, name, description, organization_id, path, data_status, last_data_at, created_at, updated_at, deleted_at, organization_deleted_at. Heavy, sent only when named: custom_fields.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": [
              "workspace:read"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "agent.read"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "first-page": {
                "summary": "List every ingest key",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "harbor": {
                "summary": "List Harbor Dental's ingest keys",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "by-name": {
                "summary": "Find Harbor Dental's ingest key by its name",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "client": {
                "summary": "List the ingest keys of Lakeside Clinic and below",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "organization_id",
            "in": "query",
            "description": "Only ingest keys of this organization.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "harbor": {
                "summary": "List Harbor Dental's ingest keys",
                "value": "0a9e0000-0000-4000-8000-000000000105"
              },
              "by-name": {
                "summary": "Find Harbor Dental's ingest key by its name",
                "value": "0a9e0000-0000-4000-8000-000000000105"
              },
              "client": {
                "summary": "List the ingest keys of Lakeside Clinic and below",
                "value": "0a9e0000-0000-4000-8000-000000000101"
              }
            }
          },
          {
            "name": "subtree",
            "in": "query",
            "description": "`true` adds the ingest keys of every organization below `organization_id`. `true` and `false` are the only values it takes.",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "examples": {
              "client": {
                "summary": "List the ingest keys of Lakeside Clinic and below",
                "value": true
              }
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Only the ingest keys with these ids. A comma-separated list of at most 100 ids matches any of them.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false,
            "x-filter": {
              "kind": "in",
              "clock": false,
              "with_updated_since": false
            }
          },
          {
            "name": "name",
            "in": "query",
            "description": "Only ingest keys of this name: the way to find a key created by a call whose answer was lost. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "kind": "eq_fold",
              "clock": false,
              "with_updated_since": false
            },
            "examples": {
              "by-name": {
                "summary": "Find Harbor Dental's ingest key by its name",
                "value": "harbor dental servers"
              }
            }
          },
          {
            "name": "inactive_before",
            "in": "query",
            "description": "Only ingest keys created, and last sending data, before this time: keys gone quiet, at a cutoff you choose. An RFC 3339 time.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "x-filter": {
              "kind": "before",
              "clock": false,
              "with_updated_since": false
            }
          },
          {
            "name": "deleted",
            "in": "query",
            "description": "Which ingest keys to list, by whether they or their organization are deleted.",
            "schema": {
              "type": "string",
              "enum": [
                "exclude",
                "include",
                "only"
              ],
              "default": "exclude"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "How many ingest keys a page holds: 1 to 5000, 1000 by default.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 5000
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "The `next_cursor` of the previous page, with the same filters.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "description": "Comma-separated top-level fields of each object to return instead of the default set.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false
          }
        ],
        "responses": {
          "200": {
            "description": "List ingest keys",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ingest_keys": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/IngestKey"
                      },
                      "description": "The ingest keys on this page."
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Null on the last page. Otherwise pass it as `cursor` for the next page."
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time",
                      "description": "The instant this walk's values worked out from the clock, and its filters on them, are worked out at: fixed on the first page and the same on every page after it."
                    },
                    "message": {
                      "type": "string",
                      "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
                    }
                  },
                  "required": [
                    "ingest_keys",
                    "next_cursor",
                    "as_of",
                    "message"
                  ]
                },
                "examples": {
                  "first-page": {
                    "summary": "List every ingest key",
                    "value": {
                      "as_of": "2026-11-10T15:05:00Z",
                      "ingest_keys": [
                        {
                          "id": "a9e70000-0000-4000-8000-000000000204",
                          "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                          "name": "Harbor Dental servers",
                          "description": null,
                          "organization_id": "0a9e0000-0000-4000-8000-000000000105",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000105",
                            "a9e70000-0000-4000-8000-000000000204"
                          ],
                          "data_status": "online",
                          "last_data_at": "2026-11-10T14:00:00Z",
                          "created_at": "2026-11-05T08:00:00Z",
                          "updated_at": "2026-11-10T14:00:00Z",
                          "deleted_at": null,
                          "organization_deleted_at": null
                        },
                        {
                          "id": "a9e70000-0000-4000-8000-000000000205",
                          "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                          "name": "Lakeside Clinic firewall",
                          "description": "Syslog from the front office firewall",
                          "organization_id": "0a9e0000-0000-4000-8000-000000000101",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000101",
                            "a9e70000-0000-4000-8000-000000000205"
                          ],
                          "data_status": "online",
                          "last_data_at": "2026-11-10T15:00:00Z",
                          "created_at": "2026-11-03T14:00:00Z",
                          "updated_at": "2026-11-10T15:00:00Z",
                          "deleted_at": null,
                          "organization_deleted_at": null
                        }
                      ],
                      "message": "ingest keys retrieved",
                      "next_cursor": null
                    }
                  },
                  "harbor": {
                    "summary": "List Harbor Dental's ingest keys",
                    "value": {
                      "as_of": "2026-11-10T15:05:00Z",
                      "ingest_keys": [
                        {
                          "id": "a9e70000-0000-4000-8000-000000000204",
                          "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                          "name": "Harbor Dental servers",
                          "description": null,
                          "organization_id": "0a9e0000-0000-4000-8000-000000000105",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000105",
                            "a9e70000-0000-4000-8000-000000000204"
                          ],
                          "data_status": "online",
                          "last_data_at": "2026-11-10T14:00:00Z",
                          "created_at": "2026-11-05T08:00:00Z",
                          "updated_at": "2026-11-10T14:00:00Z",
                          "deleted_at": null,
                          "organization_deleted_at": null
                        }
                      ],
                      "message": "ingest keys retrieved",
                      "next_cursor": null
                    }
                  },
                  "by-name": {
                    "summary": "Find Harbor Dental's ingest key by its name",
                    "value": {
                      "as_of": "2026-11-10T15:05:00Z",
                      "ingest_keys": [
                        {
                          "id": "a9e70000-0000-4000-8000-000000000204",
                          "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                          "name": "Harbor Dental servers",
                          "description": null,
                          "organization_id": "0a9e0000-0000-4000-8000-000000000105",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000105",
                            "a9e70000-0000-4000-8000-000000000204"
                          ],
                          "data_status": "online",
                          "last_data_at": "2026-11-10T14:00:00Z",
                          "created_at": "2026-11-05T08:00:00Z",
                          "updated_at": "2026-11-10T14:00:00Z",
                          "deleted_at": null,
                          "organization_deleted_at": null
                        }
                      ],
                      "message": "ingest keys retrieved",
                      "next_cursor": null
                    }
                  },
                  "client": {
                    "summary": "List the ingest keys of Lakeside Clinic and below",
                    "value": {
                      "as_of": "2026-11-10T15:05:00Z",
                      "ingest_keys": [
                        {
                          "id": "a9e70000-0000-4000-8000-000000000205",
                          "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                          "name": "Lakeside Clinic firewall",
                          "description": "Syslog from the front office firewall",
                          "organization_id": "0a9e0000-0000-4000-8000-000000000101",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000101",
                            "a9e70000-0000-4000-8000-000000000205"
                          ],
                          "data_status": "online",
                          "last_data_at": "2026-11-10T15:00:00Z",
                          "created_at": "2026-11-03T14:00:00Z",
                          "updated_at": "2026-11-10T15:00:00Z",
                          "deleted_at": null,
                          "organization_deleted_at": null
                        }
                      ],
                      "message": "ingest keys retrieved",
                      "next_cursor": null
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, one given twice, or `fields` naming a field it does not have.\n`APP_API_ERR_BAD_PARAMETERS`: A filter's value is empty, names an empty item, is not one of the values the filter takes, or is not an id or a time where the filter asks for one; `parameter` names the filter.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `organization_id` is not a UUID, `subtree` is neither `true` nor `false` or comes without `organization_id`, `deleted` is not a value it takes, or `limit` is out of range, or `cursor` cannot be read or was sent with other filters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `organization.read` and `agent.read`. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/ingest-keys/{id}": {
      "patch": {
        "operationId": "updateIngestKey",
        "tags": [
          "ingest-keys"
        ],
        "summary": "Update an ingest key",
        "description": "Changes an ingest key's name, description or custom fields; a field left out keeps its value. Needs `agent.write` at its organization.\n\nAccess: Needs `agent.write`. `agent.write` applies at each organization a grant covers and every organization below it. `agent.write` also admits changing and moving ingest keys.\n\nUnknown input: An unknown or repeated query parameter returns 400. An unknown body field returns 400.",
        "security": [
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "agent.write"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "rename": {
                "summary": "Rename an ingest key",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The ingest key's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "rename": {
                "summary": "Rename an ingest key",
                "value": "a9e70000-0000-4000-8000-000000000204"
              }
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IngestKeyUpdate"
              },
              "examples": {
                "rename": {
                  "summary": "Rename an ingest key",
                  "value": {
                    "name": "Harbor Dental server room"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update an ingest key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IDResult"
                },
                "examples": {
                  "rename": {
                    "summary": "Rename an ingest key",
                    "value": {
                      "message": "ingest key updated",
                      "id": "a9e70000-0000-4000-8000-000000000204"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`.\n`APP_API_ERR_BAD_PARAMETERS`: `name` is empty.\n`APP_API_ERR_PARAMETER_TOO_LONG`: `name` is longer than 128 characters, or `description` longer than 2048.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: The ingest key does not exist, is in another workspace or is outside your reach, `id` names a SparkLogs Agent, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteIngestKey",
        "tags": [
          "ingest-keys"
        ],
        "summary": "Delete an ingest key",
        "description": "Marks an ingest key deleted; senders using it are refused from then on, and `cache_clear_status` says whether every region refuses it. Needs `agent.delete` at its organization. Deleting a deleted key changes nothing. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 2 hours.\n\nAccess: Needs `agent.delete`. `agent.delete` applies at each organization a grant covers and every organization below it. `agent.delete` also admits deleting and restoring ingest keys.\n\nUnknown input: An unknown or repeated query parameter returns 400. A delete takes no body: its options are query parameters, and a body carrying anything returns 400.",
        "security": [
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "agent.delete"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "offboard": {
                "summary": "Delete a client's ingest key",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "agent-id": {
                "summary": "The id of a SparkLogs Agent",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The ingest key's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "offboard": {
                "summary": "Delete a client's ingest key",
                "value": "a9e70000-0000-4000-8000-000000000205"
              },
              "agent-id": {
                "summary": "The id of a SparkLogs Agent",
                "value": "a9e70000-0000-4000-8000-000000000201"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Delete an ingest key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WriteResult"
                },
                "examples": {
                  "offboard": {
                    "summary": "Delete a client's ingest key",
                    "value": {
                      "message": "ingest key deleted",
                      "cache_clear_status": "ok"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, or one given twice.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The request carries a body other than nothing, `null` or `{}`: a delete takes none, and its options are query parameters; `parameter` names the body's first field, or `body`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: The ingest key does not exist, is in another workspace or is outside your reach, `id` names a SparkLogs Agent, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "agent-id": {
                    "summary": "The id of a SparkLogs Agent",
                    "value": {
                      "at_org": true,
                      "cause": "no_privilege",
                      "error": "this credential does not have the privileges to perform this action on this organization",
                      "error_code": "APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION",
                      "privilege": "agent.delete"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "readIngestKey",
        "tags": [
          "ingest-keys"
        ],
        "summary": "Read an ingest key",
        "description": "Returns one ingest key you can see, deleted or not, without its secret. One you cannot see returns 404, as one that does not exist does, and so does the id of a SparkLogs Agent.\n\nAccess: Needs `agent.read`. `agent.read` applies at each organization a grant covers and every organization below it. `agent.read` also admits reading ingest keys, but never their secrets.\n\nFields sent by default: id, workspace_id, name, description, organization_id, path, data_status, last_data_at, created_at, updated_at, deleted_at, organization_deleted_at. Heavy, sent only when named: custom_fields.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": [
              "workspace:read"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "agent.read"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "read": {
                "summary": "Read an ingest key",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The ingest key's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "read": {
                "summary": "Read an ingest key",
                "value": "a9e70000-0000-4000-8000-000000000204"
              }
            }
          },
          {
            "name": "fields",
            "in": "query",
            "description": "Comma-separated top-level fields of each object to return instead of the default set.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false
          }
        ],
        "responses": {
          "200": {
            "description": "Read an ingest key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ingest_key": {
                      "$ref": "#/components/schemas/IngestKey",
                      "description": "The ingest key."
                    },
                    "message": {
                      "type": "string",
                      "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
                    }
                  },
                  "required": [
                    "ingest_key",
                    "message"
                  ]
                },
                "examples": {
                  "read": {
                    "summary": "Read an ingest key",
                    "value": {
                      "ingest_key": {
                        "id": "a9e70000-0000-4000-8000-000000000204",
                        "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
                        "name": "Harbor Dental servers",
                        "description": null,
                        "organization_id": "0a9e0000-0000-4000-8000-000000000105",
                        "path": [
                          "0a9e0000-0000-4000-8000-000000000100",
                          "0a9e0000-0000-4000-8000-000000000105",
                          "a9e70000-0000-4000-8000-000000000204"
                        ],
                        "data_status": "online",
                        "last_data_at": "2026-11-10T14:00:00Z",
                        "created_at": "2026-11-05T08:00:00Z",
                        "updated_at": "2026-11-10T14:00:00Z",
                        "deleted_at": null,
                        "organization_deleted_at": null
                      },
                      "message": "ingest key retrieved"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, one given twice, or `fields` naming a field it does not have.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `organization.read` and `agent.read`. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`APP_API_ERR_RECORD_NOT_FOUND`: No such ingest key, or one you cannot see; a SparkLogs Agent's id answers this too.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/ingest-keys/{id}/move": {
      "post": {
        "operationId": "moveIngestKey",
        "tags": [
          "ingest-keys"
        ],
        "summary": "Move an ingest key",
        "description": "Moves an ingest key to another organization; data sent with it from then on belongs to the new one. Needs `agent.write` at its organization and `ingest_key.create` at the new one. Moving it where it already is changes nothing. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 2 hours.\n\nAccess: Needs `agent.write` at the organization it is in now and `ingest_key.create` at the organization it moves to. `agent.write` applies at each organization a grant covers and every organization below it. `agent.write` also admits changing and moving ingest keys. `ingest_key.create` applies at each organization a grant covers and every organization below it. `ingest_key.create` also admits moving a SparkLogs Agent or an ingest key into an organization, with `agent.write` at the one it leaves.\n\nUnknown input: An unknown or repeated query parameter returns 400. An unknown body field returns 400.",
        "security": [
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "agent.write",
          "ingest_key.create"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "move": {
                "summary": "Move an ingest key to Lakeside Clinic",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The ingest key's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "move": {
                "summary": "Move an ingest key to Lakeside Clinic",
                "value": "a9e70000-0000-4000-8000-000000000204"
              }
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IngestKeyMove"
              },
              "examples": {
                "move": {
                  "summary": "Move an ingest key to Lakeside Clinic",
                  "value": {
                    "organization_id": "0a9e0000-0000-4000-8000-000000000101"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Move an ingest key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WriteResult"
                },
                "examples": {
                  "move": {
                    "summary": "Move an ingest key to Lakeside Clinic",
                    "value": {
                      "message": "ingest key moved",
                      "cache_clear_status": "ok"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`.\n`APP_API_ERR_MISSING_PARAMETER`: `organization_id` is left out.\n`APP_API_ERR_BAD_PARAMETERS`: `organization_id` is not a UUID, or names a deleted organization for a live key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: The ingest key or the new organization does not exist or is outside your reach, `id` names a SparkLogs Agent, or you do not hold `agent.write` at the key's organization and `ingest_key.create` at the new one. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/ingest-keys/{id}/restore": {
      "post": {
        "operationId": "restoreIngestKey",
        "tags": [
          "ingest-keys"
        ],
        "summary": "Restore a deleted ingest key",
        "description": "Restores a deleted ingest key, so senders using it are accepted again. Needs `agent.delete` at its organization. Restoring a live key changes nothing. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 2 hours.\n\nAccess: Needs `agent.delete`. `agent.delete` applies at each organization a grant covers and every organization below it. `agent.delete` also admits deleting and restoring ingest keys.\n\nUnknown input: An unknown or repeated query parameter returns 400. It takes no body: a body field returns 400.",
        "security": [
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "agent.delete"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "restore": {
                "summary": "Restore a deleted ingest key",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The ingest key's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "restore": {
                "summary": "Restore a deleted ingest key",
                "value": "a9e70000-0000-4000-8000-000000000205"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Restore a deleted ingest key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WriteResult"
                },
                "examples": {
                  "restore": {
                    "summary": "Restore a deleted ingest key",
                    "value": {
                      "message": "ingest key restored",
                      "cache_clear_status": "ok"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, or names a field: the call takes none.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: The ingest key does not exist, is in another workspace or is outside your reach, `id` names a SparkLogs Agent, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`APP_API_ERR_CANNOT_RESTORE_PARENT_DELETED`: Its organization is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/ingest-keys/{id}/rotate": {
      "post": {
        "operationId": "rotateIngestKey",
        "tags": [
          "ingest-keys"
        ],
        "summary": "Replace an ingest key's secret",
        "description": "Replaces the key senders present with a new one and returns it; senders still using the old key are refused from then on, and `cache_clear_status` says whether every region refuses it. Needs `ingest_key.rotate` at the ingest key's organization. Every call is recorded in the audit log. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 2 hours.\n\nAccess: Needs `ingest_key.rotate`. `ingest_key.rotate` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400. It takes no body: a body field returns 400.\n\nSecret: The response carries a secret and is sent with `Cache-Control: no-store`. Keep it out of caches and logs.",
        "security": [
          {
            "bearer": [
              "fleet:deploy"
            ]
          },
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "ingest_key.rotate"
        ],
        "x-returns-secret": true,
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "rotate": {
                "summary": "Replace an ingest key's secret",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The ingest key's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "rotate": {
                "summary": "Replace an ingest key's secret",
                "value": "a9e70000-0000-4000-8000-000000000204"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Replace an ingest key's secret",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IngestKeyRotated"
                },
                "examples": {
                  "rotate": {
                    "summary": "Replace an ingest key's secret",
                    "value": {
                      "message": "key replaced",
                      "key": "EXAMPLE-NEW-INGEST-KEY-NOT-A-REAL-SECRET",
                      "cache_clear_status": "ok"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, or names a field: the call takes none.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: You do not hold `ingest_key.rotate` at its organization, or it is missing, outside your reach or a SparkLogs Agent. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`APP_API_ERR_CONFLICT`: The ingest key is deleted: restore it first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/ingest-keys/{id}/secret": {
      "get": {
        "operationId": "revealIngestKey",
        "tags": [
          "ingest-keys"
        ],
        "summary": "Read an ingest key's secret",
        "description": "Returns the key senders present. It changes nothing. Needs `ingest_key.reveal` at the ingest key's organization. Every call is recorded in the audit log.\n\nAccess: Needs `ingest_key.reveal`. `ingest_key.reveal` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400.\n\nSecret: The response carries a secret and is sent with `Cache-Control: no-store`. Keep it out of caches and logs.",
        "security": [
          {
            "bearer": [
              "fleet:deploy"
            ]
          },
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "ingest_key.reveal"
        ],
        "x-returns-secret": true,
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "read": {
                "summary": "Read an ingest key's secret",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The ingest key's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "read": {
                "summary": "Read an ingest key's secret",
                "value": "a9e70000-0000-4000-8000-000000000204"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Read an ingest key's secret",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IngestKeySecret"
                },
                "examples": {
                  "read": {
                    "summary": "Read an ingest key's secret",
                    "value": {
                      "message": "key retrieved",
                      "key": "EXAMPLE-INGEST-KEY-NOT-A-REAL-SECRET"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, or one given twice.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: You do not hold `ingest_key.reveal` at its organization, or it is missing, outside your reach or a SparkLogs Agent. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`APP_API_ERR_CONFLICT`: The ingest key is deleted: restore it first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/ingest-policy": {
      "patch": {
        "operationId": "updateIngestPolicy",
        "tags": [
          "workspaces"
        ],
        "summary": "Update the ingest policy",
        "description": "Merges changes into the workspace's ingest policy and returns it. Needs `workspace.write`. A merge that leaves the policy as it was writes nothing, so a call with no `ingest_policy` reads the stored policy; read-workspace with `fields=settings` also returns it in `settings.ingest_policy`.\n\nAccess: Needs `workspace.write`. `workspace.write` applies to the workspace itself: a grant over every organization, or over the workspace, carries it.\n\nUnknown input: An unknown or repeated query parameter returns 400. An unknown body field returns 400.",
        "security": [
          {
            "bearer": [
              "admin:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "workspace.write"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "cap-uncurated": {
                "summary": "Cap uncurated events at warning",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IngestPolicyUpdate"
              },
              "examples": {
                "cap-uncurated": {
                  "summary": "Cap uncurated events at warning",
                  "value": {
                    "ingest_policy": {
                      "uncurated_max_severity": 13
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update the ingest policy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IngestPolicyUpdated"
                },
                "examples": {
                  "cap-uncurated": {
                    "summary": "Cap uncurated events at warning",
                    "value": {
                      "message": "ingest policy saved",
                      "ingest_policy": {
                        "uncurated_max_severity": 13
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`.\n`APP_API_ERR_BAD_PARAMETERS`: `ingest_policy` is not an object, names a key it does not take, holds a severity that is not a whole number from 1 to 24, or is larger than 4096 bytes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `workspace.write`. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/invitations": {
      "post": {
        "operationId": "createInvitation",
        "tags": [
          "invitations"
        ],
        "summary": "Invite a person",
        "description": "Invites an email address to the workspace with the grants it holds once accepted, or saves a pending invitation again: the one `invitation_id` names, or with `invitation_id` left out the email's own. Sending the same `invitation_id` again saves the same invitation, so a retry is safe. It returns 409 for an email that belongs to a member, whether or not you can see them, for an email with a pending invitation under a different `invitation_id`, and, with `invitation_id` left out, for one whose pending invitation carries grants you may not change. Needs `member.manage`, and each grant must sit inside what you may grant. Saving does not send the email; sending it is its own call.\n\nAccess: Needs `member.manage`. `member.manage` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400. An unknown body field returns 400.",
        "security": [
          {
            "bearer": [
              "admin:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "member.manage"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "invite": {
                "summary": "Invite a person as an analyst for Oakridge Medical",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "save-again": {
                "summary": "Save Casey's pending invitation again by its id, now as an engineer for Oakridge Medical",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "client-admin": {
                "summary": "Invite Lakeside Clinic's IT administrator as Organization Administrator there",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InvitationCreate"
              },
              "examples": {
                "invite": {
                  "summary": "Invite a person as an analyst for Oakridge Medical",
                  "value": {
                    "email": "casey.nguyen@example.com",
                    "grants": [
                      {
                        "role_id": "analyst",
                        "scope": {
                          "kind": "selected",
                          "org_ids": [
                            "0a9e0000-0000-4000-8000-000000000103"
                          ]
                        }
                      }
                    ],
                    "invitation_id": "1a7e0000-0000-4000-8000-000000000601"
                  }
                },
                "save-again": {
                  "summary": "Save Casey's pending invitation again by its id, now as an engineer for Oakridge Medical",
                  "value": {
                    "email": "casey.nguyen@example.com",
                    "grants": [
                      {
                        "role_id": "engineer",
                        "scope": {
                          "kind": "selected",
                          "org_ids": [
                            "0a9e0000-0000-4000-8000-000000000103"
                          ]
                        }
                      }
                    ],
                    "invitation_id": "1a7e0000-0000-4000-8000-000000000601"
                  }
                },
                "client-admin": {
                  "summary": "Invite Lakeside Clinic's IT administrator as Organization Administrator there",
                  "value": {
                    "email": "jordan.lee@example.com",
                    "grants": [
                      {
                        "role_id": "organization_admin",
                        "scope": {
                          "kind": "selected",
                          "org_ids": [
                            "0a9e0000-0000-4000-8000-000000000101"
                          ]
                        }
                      }
                    ],
                    "invitation_id": "1a7e0000-0000-4000-8000-000000000602"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Invite a person",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IDResult"
                },
                "examples": {
                  "invite": {
                    "summary": "Invite a person as an analyst for Oakridge Medical",
                    "value": {
                      "message": "invitation saved",
                      "id": "1a7e0000-0000-4000-8000-000000000601"
                    }
                  },
                  "save-again": {
                    "summary": "Save Casey's pending invitation again by its id, now as an engineer for Oakridge Medical",
                    "value": {
                      "message": "invitation saved",
                      "id": "1a7e0000-0000-4000-8000-000000000601"
                    }
                  },
                  "client-admin": {
                    "summary": "Invite Lakeside Clinic's IT administrator as Organization Administrator there",
                    "value": {
                      "message": "invitation saved",
                      "id": "1a7e0000-0000-4000-8000-000000000602"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`.\n`APP_API_ERR_MISSING_PARAMETER`: `email` is empty, `grants` is left out or null, or a grant names no role.\n`APP_API_ERR_BAD_PARAMETERS`: `email` holds no `@`, `invitation_id` is not a UUID, or a grant names a role the workspace does not have, or a malformed scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `member.manage`. The same refusal comes when the path names a workspace other than the token's own.\n`APP_API_ERR_BEYOND_OWN_AUTHORITY`: The grants reach beyond what you may grant, `grants` is empty and you do not hold `member.manage` over every organization, or the invitation saved again carries grants beyond your reach. `cause` is `token_scope` only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`APP_API_ERR_RECORD_NOT_FOUND`: `invitation_id` names an invitation of another workspace, or one you cannot see.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`APP_API_ERR_INVITATION_EMAIL_TAKEN`: The email belongs to a member, whether or not you can see them, a deleted account still in the workspace included; or it has a pending invitation and the body names a different `invitation_id`, or names none and that invitation carries grants you may not change.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listInvitations",
        "tags": [
          "invitations"
        ],
        "summary": "List invitations",
        "description": "Returns the workspace's pending invitations, each with the grants it carries, a page at a time, oldest first. Needs `member.read`; you see the invitations whose grants your reach contains, and every one you sent.\n\nAccess: Needs `member.read`. `member.read` applies at each organization a grant covers and every organization below it. A caller who reaches no organization gets an empty list.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": [
              "admin:read"
            ]
          },
          {
            "bearer": [
              "admin:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "member.read"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "list": {
                "summary": "List pending invitations",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "before-invite": {
                "summary": "Look for a pending invitation to Casey before he is invited",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "before-client-admin": {
                "summary": "Look for a pending invitation to Lakeside Clinic's IT administrator",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "by-email": {
                "summary": "Look for a pending invitation to Sam's email address",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "email",
            "in": "query",
            "description": "Only invitations to this email address. One you are not shown answers an empty page, as one never sent does. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "kind": "eq_fold",
              "clock": false,
              "with_updated_since": false
            },
            "examples": {
              "before-invite": {
                "summary": "Look for a pending invitation to Casey before he is invited",
                "value": "casey.nguyen@example.com"
              },
              "before-client-admin": {
                "summary": "Look for a pending invitation to Lakeside Clinic's IT administrator",
                "value": "jordan.lee@example.com"
              },
              "by-email": {
                "summary": "Look for a pending invitation to Sam's email address",
                "value": "sam.chen@example.com"
              }
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "How many invitations a page holds: 1 to 5000, 1000 by default.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 5000,
              "default": 1000
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "The `next_cursor` of the previous page, with the same filters.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List invitations",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvitationPage"
                },
                "examples": {
                  "list": {
                    "summary": "List pending invitations",
                    "value": {
                      "message": "invitations retrieved",
                      "invitations": [
                        {
                          "id": "1a7e0000-0000-4000-8000-000000000601",
                          "email": "casey.nguyen@example.com",
                          "grants": [
                            {
                              "role_id": "analyst",
                              "scope": {
                                "kind": "selected",
                                "org_ids": [
                                  "0a9e0000-0000-4000-8000-000000000103"
                                ],
                                "inherited": false,
                                "other_orgs": false
                              }
                            }
                          ],
                          "other_grants": false,
                          "created_at": "2026-11-08T09:00:00Z",
                          "updated_at": "2026-11-08T09:00:00Z",
                          "last_sent_at": "2026-11-08T09:00:00Z",
                          "expires_at": "2027-02-06T09:00:00Z",
                          "invited_by_user_id": "AlexRiveraExampleUserId00001",
                          "sender_removed": false
                        }
                      ],
                      "next_cursor": null
                    }
                  },
                  "before-invite": {
                    "summary": "Look for a pending invitation to Casey before he is invited",
                    "value": {
                      "message": "invitations retrieved",
                      "invitations": [],
                      "next_cursor": null
                    }
                  },
                  "before-client-admin": {
                    "summary": "Look for a pending invitation to Lakeside Clinic's IT administrator",
                    "value": {
                      "message": "invitations retrieved",
                      "invitations": [],
                      "next_cursor": null
                    }
                  },
                  "by-email": {
                    "summary": "Look for a pending invitation to Sam's email address",
                    "value": {
                      "message": "invitations retrieved",
                      "invitations": [],
                      "next_cursor": null
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, or one given twice.\n`APP_API_ERR_BAD_PARAMETERS`: A filter's value is empty, names an empty item, is not one of the values the filter takes, or is not an id or a time where the filter asks for one; `parameter` names the filter.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `limit` is not 1 to 5000, or `cursor` cannot be read or was sent with other filters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `member.read`. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/invitations/{id}": {
      "delete": {
        "operationId": "deleteInvitation",
        "tags": [
          "invitations"
        ],
        "summary": "Withdraw an invitation",
        "description": "Withdraws a pending invitation, so it can no longer be accepted. Needs `member.manage`, and the invitation's grants must sit inside your reach.\n\nAccess: Needs `member.manage`. `member.manage` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400. A delete takes no body: its options are query parameters, and a body carrying anything returns 400.",
        "security": [
          {
            "bearer": [
              "admin:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "member.manage"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "withdraw": {
                "summary": "Withdraw an invitation",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The invitation's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "withdraw": {
                "summary": "Withdraw an invitation",
                "value": "1a7e0000-0000-4000-8000-000000000601"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Withdraw an invitation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WriteResult"
                },
                "examples": {
                  "withdraw": {
                    "summary": "Withdraw an invitation",
                    "value": {
                      "message": "invitation deleted"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, or one given twice.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The request carries a body other than nothing, `null` or `{}`: a delete takes none, and its options are query parameters; `parameter` names the body's first field, or `body`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `member.manage`. The same refusal comes when the path names a workspace other than the token's own.\n`APP_API_ERR_BEYOND_OWN_AUTHORITY`: The invitation carries grants beyond your reach. `cause` is `token_scope` only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`APP_API_ERR_RECORD_NOT_FOUND`: No such pending invitation, or one you cannot see.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/invitations/{id}/send": {
      "post": {
        "operationId": "sendInvitation",
        "tags": [
          "invitations"
        ],
        "summary": "Send an invitation email",
        "description": "Sends, or sends again, the email of a pending invitation, and moves its expiry 90 days out. Needs `member.manage`. Each API token may send 500 every 5 minutes, and a signed-in person 5 every 30 seconds; a send past that returns 429 with `Retry-After`.\n\nAccess: Needs `member.manage`. `member.manage` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400. It takes no body: a body field returns 400.",
        "security": [
          {
            "bearer": [
              "admin:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "member.manage"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "send": {
                "summary": "Send the invitation email",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "client-admin": {
                "summary": "Send the client administrator's invitation email",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The invitation's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "send": {
                "summary": "Send the invitation email",
                "value": "1a7e0000-0000-4000-8000-000000000601"
              },
              "client-admin": {
                "summary": "Send the client administrator's invitation email",
                "value": "1a7e0000-0000-4000-8000-000000000602"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Send an invitation email",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WriteResult"
                },
                "examples": {
                  "send": {
                    "summary": "Send the invitation email",
                    "value": {
                      "message": "sent invitation"
                    }
                  },
                  "client-admin": {
                    "summary": "Send the client administrator's invitation email",
                    "value": {
                      "message": "sent invitation"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, or names a field: the call takes none.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `member.manage`. The same refusal comes when the path names a workspace other than the token's own.\n`APP_API_ERR_BEYOND_OWN_AUTHORITY`: The invitation carries grants beyond your reach. `cause` is `token_scope` only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`APP_API_ERR_RECORD_NOT_FOUND`: No such pending invitation in the workspace, checked before your privilege.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`APP_API_ERR_CONFLICT`: The invitation was declined.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: You sent more invitations than the send limit allows (`cause` `send_limit`); `Retry-After` says when to try again.\n`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/members": {
      "get": {
        "operationId": "listMembers",
        "tags": [
          "members"
        ],
        "summary": "List members",
        "description": "Returns the workspace's members, deleted accounts included, each with its grants, a page at a time, oldest membership first. Needs `member.read`; you see the members your reach contains, with their grants inside it. Pending invitations are listed by `list-invitations`. A workspace token's grants are not listed here; the app lists them, and they change through the grant calls. Without `member.read` over every organization, a member is listed only through a grant at or below an organization you reach, so a member with no such grant, or none at all, is not listed.\n\nAccess: Needs `member.read`. `member.read` applies at each organization a grant covers and every organization below it. A caller who reaches no organization gets an empty list.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": [
              "admin:read"
            ]
          },
          {
            "bearer": [
              "admin:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "member.read"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "list": {
                "summary": "List members",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "clients-admin": {
                "summary": "List the members a token granted Organization Administrator over the clients sees",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "by-email": {
                "summary": "Find Sam by his email address",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "before-invite": {
                "summary": "Look for Casey among the members before he is invited",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "accepted": {
                "summary": "Find Casey again after he accepted the invitation",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "before-client-admin": {
                "summary": "Look for Lakeside Clinic's IT administrator among the members before she is invited",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "client-admin-accepted": {
                "summary": "Find Lakeside Clinic's IT administrator after she accepted",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "after-removal": {
                "summary": "Look for Sam again after he is removed",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "email",
            "in": "query",
            "description": "Only the member with this email address. A person you are not shown answers an empty page, as one who is no member does. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "kind": "eq_fold",
              "clock": false,
              "with_updated_since": false
            },
            "examples": {
              "by-email": {
                "summary": "Find Sam by his email address",
                "value": "sam.chen@example.com"
              },
              "before-invite": {
                "summary": "Look for Casey among the members before he is invited",
                "value": "casey.nguyen@example.com"
              },
              "accepted": {
                "summary": "Find Casey again after he accepted the invitation",
                "value": "casey.nguyen@example.com"
              },
              "before-client-admin": {
                "summary": "Look for Lakeside Clinic's IT administrator among the members before she is invited",
                "value": "jordan.lee@example.com"
              },
              "client-admin-accepted": {
                "summary": "Find Lakeside Clinic's IT administrator after she accepted",
                "value": "jordan.lee@example.com"
              },
              "after-removal": {
                "summary": "Look for Sam again after he is removed",
                "value": "sam.chen@example.com"
              }
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "How many members a page holds: 1 to 5000, 1000 by default.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 5000,
              "default": 1000
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "The `next_cursor` of the previous page, with the same filters.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List members",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemberPage"
                },
                "examples": {
                  "list": {
                    "summary": "List members",
                    "value": {
                      "message": "members retrieved",
                      "members": [
                        {
                          "user_id": "AlexRiveraExampleUserId00001",
                          "email": "alex.rivera@example.com",
                          "full_name": "Alex Rivera",
                          "display_name": "Alex",
                          "is_self": false,
                          "created_at": "2026-11-01T09:00:00Z",
                          "deleted_at": null,
                          "grants": [
                            {
                              "id": "6a170000-0000-4000-8000-000000000501",
                              "role_id": "admin",
                              "scope": {
                                "kind": "all",
                                "org_ids": [],
                                "inherited": false,
                                "other_orgs": false
                              }
                            }
                          ],
                          "other_grants": false,
                          "groups": []
                        },
                        {
                          "user_id": "SamChenExampleUserId00000002",
                          "email": "sam.chen@example.com",
                          "full_name": "Sam Chen",
                          "display_name": "Sam",
                          "is_self": false,
                          "created_at": "2026-11-02T10:00:00Z",
                          "deleted_at": null,
                          "grants": [
                            {
                              "id": "6a170000-0000-4000-8000-000000000502",
                              "role_id": "engineer",
                              "scope": {
                                "kind": "selected",
                                "org_ids": [
                                  "0a9e0000-0000-4000-8000-000000000101"
                                ],
                                "inherited": false,
                                "other_orgs": false
                              }
                            }
                          ],
                          "other_grants": false,
                          "groups": [
                            {
                              "id": "9a0b0000-0000-4000-8000-000000000401",
                              "name": "Helpdesk Tier 1"
                            }
                          ]
                        }
                      ],
                      "next_cursor": null
                    }
                  },
                  "clients-admin": {
                    "summary": "List the members a token granted Organization Administrator over the clients sees",
                    "value": {
                      "message": "members retrieved",
                      "members": [
                        {
                          "user_id": "SamChenExampleUserId00000002",
                          "email": "sam.chen@example.com",
                          "full_name": "Sam Chen",
                          "display_name": "Sam",
                          "is_self": false,
                          "created_at": "2026-11-02T10:00:00Z",
                          "deleted_at": null,
                          "grants": [
                            {
                              "id": "6a170000-0000-4000-8000-000000000502",
                              "role_id": "engineer",
                              "scope": {
                                "kind": "selected",
                                "org_ids": [
                                  "0a9e0000-0000-4000-8000-000000000101"
                                ],
                                "inherited": false,
                                "other_orgs": false
                              }
                            }
                          ],
                          "other_grants": false,
                          "groups": [
                            {
                              "id": "9a0b0000-0000-4000-8000-000000000401",
                              "name": "Helpdesk Tier 1"
                            }
                          ]
                        }
                      ],
                      "next_cursor": null
                    }
                  },
                  "by-email": {
                    "summary": "Find Sam by his email address",
                    "value": {
                      "message": "members retrieved",
                      "members": [
                        {
                          "user_id": "SamChenExampleUserId00000002",
                          "email": "sam.chen@example.com",
                          "full_name": "Sam Chen",
                          "display_name": "Sam",
                          "is_self": false,
                          "created_at": "2026-11-02T10:00:00Z",
                          "deleted_at": null,
                          "grants": [
                            {
                              "id": "6a170000-0000-4000-8000-000000000502",
                              "role_id": "engineer",
                              "scope": {
                                "kind": "selected",
                                "org_ids": [
                                  "0a9e0000-0000-4000-8000-000000000101"
                                ],
                                "inherited": false,
                                "other_orgs": false
                              }
                            }
                          ],
                          "other_grants": false,
                          "groups": [
                            {
                              "id": "9a0b0000-0000-4000-8000-000000000401",
                              "name": "Helpdesk Tier 1"
                            }
                          ]
                        }
                      ],
                      "next_cursor": null
                    }
                  },
                  "before-invite": {
                    "summary": "Look for Casey among the members before he is invited",
                    "value": {
                      "message": "members retrieved",
                      "members": [],
                      "next_cursor": null
                    }
                  },
                  "accepted": {
                    "summary": "Find Casey again after he accepted the invitation",
                    "value": {
                      "message": "members retrieved",
                      "members": [
                        {
                          "user_id": "CaseyNguyenExampleUserId0003",
                          "email": "casey.nguyen@example.com",
                          "full_name": "Casey Nguyen",
                          "display_name": "Casey",
                          "is_self": false,
                          "created_at": "2026-11-08T11:00:00Z",
                          "deleted_at": null,
                          "grants": [
                            {
                              "id": "6a170000-0000-4000-8000-000000000506",
                              "role_id": "analyst",
                              "scope": {
                                "kind": "selected",
                                "org_ids": [
                                  "0a9e0000-0000-4000-8000-000000000103"
                                ],
                                "inherited": false,
                                "other_orgs": false
                              }
                            }
                          ],
                          "other_grants": false,
                          "groups": []
                        }
                      ],
                      "next_cursor": null
                    }
                  },
                  "before-client-admin": {
                    "summary": "Look for Lakeside Clinic's IT administrator among the members before she is invited",
                    "value": {
                      "message": "members retrieved",
                      "members": [],
                      "next_cursor": null
                    }
                  },
                  "client-admin-accepted": {
                    "summary": "Find Lakeside Clinic's IT administrator after she accepted",
                    "value": {
                      "message": "members retrieved",
                      "members": [
                        {
                          "user_id": "JordanLeeExampleUserId000004",
                          "email": "jordan.lee@example.com",
                          "full_name": "Jordan Lee",
                          "display_name": "Jordan",
                          "is_self": false,
                          "created_at": "2026-11-09T11:00:00Z",
                          "deleted_at": null,
                          "grants": [
                            {
                              "id": "6a170000-0000-4000-8000-000000000507",
                              "role_id": "organization_admin",
                              "scope": {
                                "kind": "selected",
                                "org_ids": [
                                  "0a9e0000-0000-4000-8000-000000000101"
                                ],
                                "inherited": false,
                                "other_orgs": false
                              }
                            }
                          ],
                          "other_grants": false,
                          "groups": []
                        }
                      ],
                      "next_cursor": null
                    }
                  },
                  "after-removal": {
                    "summary": "Look for Sam again after he is removed",
                    "value": {
                      "message": "members retrieved",
                      "members": [],
                      "next_cursor": null
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, or one given twice.\n`APP_API_ERR_BAD_PARAMETERS`: A filter's value is empty, names an empty item, is not one of the values the filter takes, or is not an id or a time where the filter asks for one; `parameter` names the filter.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `limit` is not 1 to 5000, or `cursor` cannot be read or was sent with other filters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `member.read`. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/members/{user_id}": {
      "delete": {
        "operationId": "deleteMember",
        "tags": [
          "members"
        ],
        "summary": "Remove a member",
        "description": "Removes a member from the workspace with their grants, their group memberships and every personal token and connected app they hold there. Needs `member.manage`, and the member must sit inside your reach. A repeat returns 404 once the member is gone: treat that as done. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 15 minutes.\n\nAccess: Needs `member.manage`. `member.manage` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400. A delete takes no body: its options are query parameters, and a body carrying anything returns 400.",
        "security": [
          {
            "bearer": [
              "admin:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "member.manage"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "remove": {
                "summary": "Remove Sam, who holds his own grant and the helpdesk group's",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "beyond-reach": {
                "summary": "Remove Sam with Organization Administrator over Lakeside Clinic alone, while his helpdesk group also covers Harbor Dental",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "user_id",
            "in": "path",
            "required": true,
            "description": "The member's user id.",
            "schema": {
              "type": "string"
            },
            "examples": {
              "remove": {
                "summary": "Remove Sam, who holds his own grant and the helpdesk group's",
                "value": "SamChenExampleUserId00000002"
              },
              "beyond-reach": {
                "summary": "Remove Sam with Organization Administrator over Lakeside Clinic alone, while his helpdesk group also covers Harbor Dental",
                "value": "SamChenExampleUserId00000002"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Remove a member",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WriteResult"
                },
                "examples": {
                  "remove": {
                    "summary": "Remove Sam, who holds his own grant and the helpdesk group's",
                    "value": {
                      "message": "user removed from workspace",
                      "cache_clear_status": "ok"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, or one given twice.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The request carries a body other than nothing, `null` or `{}`: a delete takes none, and its options are query parameters; `parameter` names the body's first field, or `body`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `member.manage`. The same refusal comes when the path names a workspace other than the token's own.\n`APP_API_ERR_BEYOND_OWN_AUTHORITY`: The member holds access you do not hold yourself. `cause` is `token_scope` only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "beyond-reach": {
                    "summary": "Remove Sam with Organization Administrator over Lakeside Clinic alone, while his helpdesk group also covers Harbor Dental",
                    "value": {
                      "error": "cannot remove a user with privileges or organization access beyond your own",
                      "error_code": "APP_API_ERR_BEYOND_OWN_AUTHORITY"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "`APP_API_ERR_RECORD_NOT_FOUND`: The user is not a member, or not one you can see.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`APP_API_ERR_LAST_ADMINISTRATOR`: The change would leave no administrator over every organization. Only a signed-in session meets this: no scope carries every privilege an Administrator holds, so an API token is refused with 403 first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/onboarding": {
      "patch": {
        "operationId": "updateOnboarding",
        "tags": [
          "workspaces"
        ],
        "summary": "Update onboarding",
        "description": "Merges changes into the workspace's onboarding state and returns it. Needs `workspace.read` and `organization.write`. A merge that leaves the state as it was writes nothing, so a call with no `onboarding` reads the stored state; read-workspace with `fields=settings` also returns it in `settings.onboarding`.\n\nAccess: Needs `workspace.read` and `organization.write`. Any grant in the workspace carries `workspace.read`. `organization.write` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400. An unknown body field returns 400.",
        "security": [
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "workspace.read",
          "organization.write"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "dismiss": {
                "summary": "Dismiss the onboarding guide",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OnboardingUpdate"
              },
              "examples": {
                "dismiss": {
                  "summary": "Dismiss the onboarding guide",
                  "value": {
                    "onboarding": {
                      "dismissed_at": "2026-11-10T09:00:00Z"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update onboarding",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingUpdated"
                },
                "examples": {
                  "dismiss": {
                    "summary": "Dismiss the onboarding guide",
                    "value": {
                      "message": "onboarding saved",
                      "onboarding": {
                        "dismissed_at": "2026-11-10T09:00:00Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`.\n`APP_API_ERR_BAD_PARAMETERS`: `onboarding` is not an object, names a key it does not take, holds a value it does not take, is larger than 16384 bytes, or holds a `wizard_state` larger than 8192 bytes or a `wizard_data` larger than 8192 bytes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `workspace.read`, and `organization.write` over every organization. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/organizations": {
      "post": {
        "operationId": "createOrganization",
        "tags": [
          "organizations"
        ],
        "summary": "Create an organization",
        "description": "Creates an organization under `parent_id`, or at the top level when `parent_id` is left out. Needs `organization.create` at the parent, or over every organization for a top-level one. Names are not unique, even among siblings. RMM and PSA client ids need not be unique either; the client id check says which organizations already record one. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 15 minutes.\n\nAccess: Needs `organization.create`. `organization.create` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400. An unknown body field returns 400.",
        "security": [
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "organization.create"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "child": {
                "summary": "Create Finance, a site of Lakeside Clinic, under it",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "scope-refused": {
                "summary": "A token whose scopes leave the privilege out",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "client": {
                "summary": "Create Lakeside Clinic, a PSA client, under the organization that holds the clients",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "new-company": {
                "summary": "Create Pine Ridge Dental, a company new in the PSA, under the organization that holds the clients",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "top-level": {
                "summary": "Create the organization that holds the clients, at the top of the tree",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrganizationCreate"
              },
              "examples": {
                "child": {
                  "summary": "Create Finance, a site of Lakeside Clinic, under it",
                  "value": {
                    "name": "Finance",
                    "parent_id": "0a9e0000-0000-4000-8000-000000000101"
                  }
                },
                "scope-refused": {
                  "summary": "A token whose scopes leave the privilege out",
                  "value": {
                    "name": "Finance",
                    "parent_id": "0a9e0000-0000-4000-8000-000000000101"
                  }
                },
                "client": {
                  "summary": "Create Lakeside Clinic, a PSA client, under the organization that holds the clients",
                  "value": {
                    "description": "Family practice, two sites",
                    "name": "Lakeside Clinic",
                    "parent_id": "0a9e0000-0000-4000-8000-000000000100",
                    "psa_client_id": "10042",
                    "rmm_client_id": "LAKESIDE-01"
                  }
                },
                "new-company": {
                  "summary": "Create Pine Ridge Dental, a company new in the PSA, under the organization that holds the clients",
                  "value": {
                    "name": "Pine Ridge Dental",
                    "parent_id": "0a9e0000-0000-4000-8000-000000000100",
                    "psa_client_id": "10061",
                    "rmm_client_id": "PINERIDGE-01"
                  }
                },
                "top-level": {
                  "summary": "Create the organization that holds the clients, at the top of the tree",
                  "value": {
                    "description": "Every client of Northwind IT Services",
                    "name": "Northwind clients"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Create an organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationCreated"
                },
                "examples": {
                  "child": {
                    "summary": "Create Finance, a site of Lakeside Clinic, under it",
                    "value": {
                      "message": "organization created",
                      "id": "0a9e0000-0000-4000-8000-000000000102",
                      "cache_clear_status": "ok"
                    }
                  },
                  "client": {
                    "summary": "Create Lakeside Clinic, a PSA client, under the organization that holds the clients",
                    "value": {
                      "message": "organization created",
                      "id": "0a9e0000-0000-4000-8000-000000000101",
                      "cache_clear_status": "ok"
                    }
                  },
                  "new-company": {
                    "summary": "Create Pine Ridge Dental, a company new in the PSA, under the organization that holds the clients",
                    "value": {
                      "message": "organization created",
                      "id": "0a9e0000-0000-4000-8000-000000000106",
                      "cache_clear_status": "ok"
                    }
                  },
                  "top-level": {
                    "summary": "Create the organization that holds the clients, at the top of the tree",
                    "value": {
                      "message": "organization created",
                      "id": "0a9e0000-0000-4000-8000-000000000100",
                      "cache_clear_status": "ok"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`.\n`APP_API_ERR_MISSING_PARAMETER`: `name` is left out or empty.\n`APP_API_ERR_PARAMETER_TOO_LONG`: `name` is longer than 128 characters, `description` longer than 2048, or a client id longer than 256 characters once cleaned.\n`APP_API_ERR_BAD_PARAMETERS`: `parent_id` is not a UUID, names a deleted organization, or would make the tree deeper than 25 levels.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: You do not hold `organization.create` at `parent_id`, or `parent_id` names no organization you can see. The same refusal comes when the path names a workspace other than the token's own.\n`APP_API_ERR_NO_PRIVILEGE_ON_ALL_ORGANIZATIONS`: There is no `parent_id` and you do not hold `organization.create` over every organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "scope-refused": {
                    "summary": "A token whose scopes leave the privilege out",
                    "value": {
                      "at_org": true,
                      "cause": "token_scope",
                      "error": "this credential does not have the privileges to perform this action on the organization 0a9e0000-0000-4000-8000-000000000101",
                      "error_code": "APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION",
                      "privilege": "organization.create",
                      "required_scope": "fleet:write"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listOrganizations",
        "tags": [
          "organizations"
        ],
        "summary": "List organizations",
        "description": "Returns the organizations you can see, a page at a time, in `id` order, or least recently changed first with `updated_since`. Filters combine: a row must pass every one given. `parent_id` lists direct children, `root_id` the organization and everything below it, and `name` or a client id every organization you can see that records it; passing both client ids returns only organizations recording both. To sync, pass `updated_since` and keep the watermark of the last page: the next sync starts from it. `deleted=include` or `deleted=only` returns deleted organizations too.\n\nAccess: Needs `organization.read`. `organization.read` applies at each organization a grant covers and every organization below it. A caller who reaches no organization gets an empty list.\n\nFields sent by default: id, parent_id, path, name, description, rmm_client_id, psa_client_id, created_at, updated_at, deleted_at. Heavy, sent only when named: custom_fields.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": [
              "workspace:read"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "organization.read"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "first-page": {
                "summary": "List the organizations a read-only personal token can see",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "list": {
                "summary": "List organizations two at a time",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "with-deleted": {
                "summary": "List organizations, deleted ones included",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "full-pass": {
                "summary": "List every organization for a first sync, deleted ones included",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "sync-delta": {
                "summary": "Read what changed since the first sync, deletions included",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "by-psa-client-id": {
                "summary": "Find the organizations a PSA client id names, deleted ones included",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "by-rmm-client-id": {
                "summary": "Find the organizations an RMM client id names, deleted ones included",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "client-under-parent": {
                "summary": "Find a PSA client id at or below one organization",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "by-name": {
                "summary": "Find a site by its name under its client, after a create whose answer was lost",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "psa-client-new": {
                "summary": "Look up a PSA client id before creating its organization, deleted ones included",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "rmm-client-new": {
                "summary": "Look up an RMM client id before creating its organization, deleted ones included",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Only the organizations with these ids. A comma-separated list of at most 100 ids matches any of them.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false,
            "x-filter": {
              "kind": "in",
              "clock": false,
              "with_updated_since": true
            }
          },
          {
            "name": "parent_id",
            "in": "query",
            "description": "Only the direct children of this organization.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "x-filter": {
              "kind": "eq",
              "clock": false,
              "with_updated_since": true
            },
            "examples": {
              "by-name": {
                "summary": "Find a site by its name under its client, after a create whose answer was lost",
                "value": "0a9e0000-0000-4000-8000-000000000101"
              }
            }
          },
          {
            "name": "root_id",
            "in": "query",
            "description": "Only this organization and every organization below it.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "x-filter": {
              "kind": "eq",
              "clock": false,
              "with_updated_since": true
            },
            "examples": {
              "client-under-parent": {
                "summary": "Find a PSA client id at or below one organization",
                "value": "0a9e0000-0000-4000-8000-000000000101"
              }
            }
          },
          {
            "name": "name",
            "in": "query",
            "description": "Only organizations of this name: the way to find a site created by a call whose answer was lost. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "kind": "eq_fold",
              "clock": false,
              "with_updated_since": true
            },
            "examples": {
              "by-name": {
                "summary": "Find a site by its name under its client, after a create whose answer was lost",
                "value": "finance"
              }
            }
          },
          {
            "name": "rmm_client_id",
            "in": "query",
            "description": "Only organizations recording this RMM client id. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "kind": "eq_fold",
              "clock": false,
              "with_updated_since": true
            },
            "examples": {
              "by-rmm-client-id": {
                "summary": "Find the organizations an RMM client id names, deleted ones included",
                "value": "OAKRIDGE-01"
              },
              "rmm-client-new": {
                "summary": "Look up an RMM client id before creating its organization, deleted ones included",
                "value": "LAKESIDE-01"
              }
            }
          },
          {
            "name": "psa_client_id",
            "in": "query",
            "description": "Only organizations recording this PSA client id. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "kind": "eq_fold",
              "clock": false,
              "with_updated_since": true
            },
            "examples": {
              "by-psa-client-id": {
                "summary": "Find the organizations a PSA client id names, deleted ones included",
                "value": "10042"
              },
              "client-under-parent": {
                "summary": "Find a PSA client id at or below one organization",
                "value": "10042"
              },
              "psa-client-new": {
                "summary": "Look up a PSA client id before creating its organization, deleted ones included",
                "value": "10042"
              }
            }
          },
          {
            "name": "deleted",
            "in": "query",
            "description": "Which organizations to list, by whether they are deleted.",
            "schema": {
              "type": "string",
              "enum": [
                "exclude",
                "include",
                "only"
              ],
              "default": "exclude"
            },
            "examples": {
              "with-deleted": {
                "summary": "List organizations, deleted ones included",
                "value": "include"
              },
              "full-pass": {
                "summary": "List every organization for a first sync, deleted ones included",
                "value": "include"
              },
              "sync-delta": {
                "summary": "Read what changed since the first sync, deletions included",
                "value": "include"
              },
              "by-psa-client-id": {
                "summary": "Find the organizations a PSA client id names, deleted ones included",
                "value": "include"
              },
              "by-rmm-client-id": {
                "summary": "Find the organizations an RMM client id names, deleted ones included",
                "value": "include"
              },
              "client-under-parent": {
                "summary": "Find a PSA client id at or below one organization",
                "value": "include"
              },
              "psa-client-new": {
                "summary": "Look up a PSA client id before creating its organization, deleted ones included",
                "value": "include"
              },
              "rmm-client-new": {
                "summary": "Look up an RMM client id before creating its organization, deleted ones included",
                "value": "include"
              }
            }
          },
          {
            "name": "updated_since",
            "in": "query",
            "description": "Only organizations changed at or after this time (RFC 3339). Pass the watermark of your last complete sync.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "examples": {
              "sync-delta": {
                "summary": "Read what changed since the first sync, deletions included",
                "value": "2026-11-08T09:00:00Z"
              }
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "How many organizations a page holds: 1 to 5000, 1000 by default.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 5000
            },
            "examples": {
              "list": {
                "summary": "List organizations two at a time",
                "value": 2
              }
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "The `next_cursor` of the previous page, with the same filters.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "description": "Comma-separated top-level fields of each object to return instead of the default set.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false
          }
        ],
        "responses": {
          "200": {
            "description": "List organizations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "organizations": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Organization"
                      },
                      "description": "The organizations on this page."
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Null on the last page. Otherwise pass it as `cursor` for the next page."
                    },
                    "watermark": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Pass it as `updated_since` on your next sync."
                    },
                    "message": {
                      "type": "string",
                      "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
                    }
                  },
                  "required": [
                    "organizations",
                    "next_cursor",
                    "watermark",
                    "message"
                  ]
                },
                "examples": {
                  "first-page": {
                    "summary": "List the organizations a read-only personal token can see",
                    "value": {
                      "message": "organizations retrieved",
                      "next_cursor": null,
                      "organizations": [
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000100",
                          "parent_id": null,
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100"
                          ],
                          "name": "Northwind clients",
                          "description": "Every client of Northwind IT Services",
                          "rmm_client_id": null,
                          "psa_client_id": null,
                          "created_at": "2026-11-01T09:00:00Z",
                          "updated_at": "2026-11-01T09:00:00Z",
                          "deleted_at": null
                        },
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000101",
                          "parent_id": "0a9e0000-0000-4000-8000-000000000100",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000101"
                          ],
                          "name": "Lakeside Clinic",
                          "description": "Family practice, two sites",
                          "rmm_client_id": "LAKESIDE-01",
                          "psa_client_id": "10042",
                          "created_at": "2026-11-02T09:00:00Z",
                          "updated_at": "2026-11-02T09:00:00Z",
                          "deleted_at": null
                        },
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000102",
                          "parent_id": "0a9e0000-0000-4000-8000-000000000101",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000101",
                            "0a9e0000-0000-4000-8000-000000000102"
                          ],
                          "name": "Finance",
                          "description": null,
                          "rmm_client_id": null,
                          "psa_client_id": null,
                          "created_at": "2026-11-03T10:00:00Z",
                          "updated_at": "2026-11-03T10:00:00Z",
                          "deleted_at": null
                        },
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000103",
                          "parent_id": "0a9e0000-0000-4000-8000-000000000100",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000103"
                          ],
                          "name": "Oakridge Medical",
                          "description": null,
                          "rmm_client_id": "OAKRIDGE-01",
                          "psa_client_id": null,
                          "created_at": "2026-11-02T09:00:00Z",
                          "updated_at": "2026-11-04T11:00:00Z",
                          "deleted_at": null
                        },
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000105",
                          "parent_id": "0a9e0000-0000-4000-8000-000000000100",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000105"
                          ],
                          "name": "Harbor Dental",
                          "description": null,
                          "rmm_client_id": null,
                          "psa_client_id": "10057",
                          "created_at": "2026-11-02T09:00:00Z",
                          "updated_at": "2026-11-09T16:00:00Z",
                          "deleted_at": null
                        }
                      ],
                      "watermark": "2026-11-10T09:00:00Z"
                    }
                  },
                  "list": {
                    "summary": "List organizations two at a time",
                    "value": {
                      "message": "organizations retrieved",
                      "next_cursor": "eyJ2IjoxLCJleGFtcGxlIjp0cnVlfQ",
                      "organizations": [
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000100",
                          "parent_id": null,
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100"
                          ],
                          "name": "Northwind clients",
                          "description": "Every client of Northwind IT Services",
                          "rmm_client_id": null,
                          "psa_client_id": null,
                          "created_at": "2026-11-01T09:00:00Z",
                          "updated_at": "2026-11-01T09:00:00Z",
                          "deleted_at": null
                        },
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000101",
                          "parent_id": "0a9e0000-0000-4000-8000-000000000100",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000101"
                          ],
                          "name": "Lakeside Clinic",
                          "description": "Family practice, two sites",
                          "rmm_client_id": "LAKESIDE-01",
                          "psa_client_id": "10042",
                          "created_at": "2026-11-02T09:00:00Z",
                          "updated_at": "2026-11-02T09:00:00Z",
                          "deleted_at": null
                        }
                      ],
                      "watermark": "2026-11-10T09:00:00Z"
                    }
                  },
                  "with-deleted": {
                    "summary": "List organizations, deleted ones included",
                    "value": {
                      "message": "organizations retrieved",
                      "next_cursor": null,
                      "organizations": [
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000100",
                          "parent_id": null,
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100"
                          ],
                          "name": "Northwind clients",
                          "description": "Every client of Northwind IT Services",
                          "rmm_client_id": null,
                          "psa_client_id": null,
                          "created_at": "2026-11-01T09:00:00Z",
                          "updated_at": "2026-11-01T09:00:00Z",
                          "deleted_at": null
                        },
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000101",
                          "parent_id": "0a9e0000-0000-4000-8000-000000000100",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000101"
                          ],
                          "name": "Lakeside Clinic",
                          "description": "Family practice, two sites",
                          "rmm_client_id": "LAKESIDE-01",
                          "psa_client_id": "10042",
                          "created_at": "2026-11-02T09:00:00Z",
                          "updated_at": "2026-11-02T09:00:00Z",
                          "deleted_at": null
                        },
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000102",
                          "parent_id": "0a9e0000-0000-4000-8000-000000000101",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000101",
                            "0a9e0000-0000-4000-8000-000000000102"
                          ],
                          "name": "Finance",
                          "description": null,
                          "rmm_client_id": null,
                          "psa_client_id": null,
                          "created_at": "2026-11-03T10:00:00Z",
                          "updated_at": "2026-11-03T10:00:00Z",
                          "deleted_at": null
                        },
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000103",
                          "parent_id": "0a9e0000-0000-4000-8000-000000000100",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000103"
                          ],
                          "name": "Oakridge Medical",
                          "description": null,
                          "rmm_client_id": "OAKRIDGE-01",
                          "psa_client_id": null,
                          "created_at": "2026-11-02T09:00:00Z",
                          "updated_at": "2026-11-04T11:00:00Z",
                          "deleted_at": null
                        },
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000104",
                          "parent_id": "0a9e0000-0000-4000-8000-000000000100",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000104"
                          ],
                          "name": "Summit Accounting",
                          "description": null,
                          "rmm_client_id": null,
                          "psa_client_id": null,
                          "created_at": "2026-11-02T09:00:00Z",
                          "updated_at": "2026-11-06T14:00:00Z",
                          "deleted_at": "2026-11-06T14:00:00Z"
                        },
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000105",
                          "parent_id": "0a9e0000-0000-4000-8000-000000000100",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000105"
                          ],
                          "name": "Harbor Dental",
                          "description": null,
                          "rmm_client_id": null,
                          "psa_client_id": "10057",
                          "created_at": "2026-11-02T09:00:00Z",
                          "updated_at": "2026-11-09T16:00:00Z",
                          "deleted_at": null
                        }
                      ],
                      "watermark": "2026-11-10T09:00:00Z"
                    }
                  },
                  "full-pass": {
                    "summary": "List every organization for a first sync, deleted ones included",
                    "value": {
                      "message": "organizations retrieved",
                      "next_cursor": null,
                      "organizations": [
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000100",
                          "parent_id": null,
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100"
                          ],
                          "name": "Northwind clients",
                          "description": "Every client of Northwind IT Services",
                          "rmm_client_id": null,
                          "psa_client_id": null,
                          "created_at": "2026-11-01T09:00:00Z",
                          "updated_at": "2026-11-01T09:00:00Z",
                          "deleted_at": null
                        },
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000101",
                          "parent_id": "0a9e0000-0000-4000-8000-000000000100",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000101"
                          ],
                          "name": "Lakeside Clinic",
                          "description": "Family practice, two sites",
                          "rmm_client_id": "LAKESIDE-01",
                          "psa_client_id": "10042",
                          "created_at": "2026-11-02T09:00:00Z",
                          "updated_at": "2026-11-02T09:00:00Z",
                          "deleted_at": null
                        },
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000102",
                          "parent_id": "0a9e0000-0000-4000-8000-000000000101",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000101",
                            "0a9e0000-0000-4000-8000-000000000102"
                          ],
                          "name": "Finance",
                          "description": null,
                          "rmm_client_id": null,
                          "psa_client_id": null,
                          "created_at": "2026-11-03T10:00:00Z",
                          "updated_at": "2026-11-03T10:00:00Z",
                          "deleted_at": null
                        },
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000103",
                          "parent_id": "0a9e0000-0000-4000-8000-000000000100",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000103"
                          ],
                          "name": "Oakridge Medical",
                          "description": null,
                          "rmm_client_id": "OAKRIDGE-01",
                          "psa_client_id": null,
                          "created_at": "2026-11-02T09:00:00Z",
                          "updated_at": "2026-11-04T11:00:00Z",
                          "deleted_at": null
                        },
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000105",
                          "parent_id": "0a9e0000-0000-4000-8000-000000000100",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000105"
                          ],
                          "name": "Harbor Dental",
                          "description": null,
                          "rmm_client_id": null,
                          "psa_client_id": null,
                          "created_at": "2026-11-02T09:00:00Z",
                          "updated_at": "2026-11-05T08:00:00Z",
                          "deleted_at": null
                        },
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000104",
                          "parent_id": "0a9e0000-0000-4000-8000-000000000100",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000104"
                          ],
                          "name": "Summit Accounting",
                          "description": null,
                          "rmm_client_id": null,
                          "psa_client_id": null,
                          "created_at": "2026-11-02T09:00:00Z",
                          "updated_at": "2026-11-06T14:00:00Z",
                          "deleted_at": "2026-11-06T14:00:00Z"
                        }
                      ],
                      "watermark": "2026-11-08T09:00:00Z"
                    }
                  },
                  "sync-delta": {
                    "summary": "Read what changed since the first sync, deletions included",
                    "value": {
                      "message": "organizations retrieved",
                      "next_cursor": null,
                      "organizations": [
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000105",
                          "parent_id": "0a9e0000-0000-4000-8000-000000000100",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000105"
                          ],
                          "name": "Harbor Dental",
                          "description": null,
                          "rmm_client_id": null,
                          "psa_client_id": "10057",
                          "created_at": "2026-11-02T09:00:00Z",
                          "updated_at": "2026-11-09T16:00:00Z",
                          "deleted_at": null
                        }
                      ],
                      "watermark": "2026-11-10T09:00:00Z"
                    }
                  },
                  "by-psa-client-id": {
                    "summary": "Find the organizations a PSA client id names, deleted ones included",
                    "value": {
                      "message": "organizations retrieved",
                      "next_cursor": null,
                      "organizations": [
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000101",
                          "parent_id": "0a9e0000-0000-4000-8000-000000000100",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000101"
                          ],
                          "name": "Lakeside Clinic",
                          "description": "Family practice, two sites",
                          "rmm_client_id": "LAKESIDE-01",
                          "psa_client_id": "10042",
                          "created_at": "2026-11-02T09:00:00Z",
                          "updated_at": "2026-11-02T09:00:00Z",
                          "deleted_at": null
                        }
                      ],
                      "watermark": "2026-11-10T09:00:00Z"
                    }
                  },
                  "by-rmm-client-id": {
                    "summary": "Find the organizations an RMM client id names, deleted ones included",
                    "value": {
                      "message": "organizations retrieved",
                      "next_cursor": null,
                      "organizations": [
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000103",
                          "parent_id": "0a9e0000-0000-4000-8000-000000000100",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000103"
                          ],
                          "name": "Oakridge Medical",
                          "description": null,
                          "rmm_client_id": "OAKRIDGE-01",
                          "psa_client_id": null,
                          "created_at": "2026-11-02T09:00:00Z",
                          "updated_at": "2026-11-04T11:00:00Z",
                          "deleted_at": null
                        }
                      ],
                      "watermark": "2026-11-10T09:00:00Z"
                    }
                  },
                  "client-under-parent": {
                    "summary": "Find a PSA client id at or below one organization",
                    "value": {
                      "message": "organizations retrieved",
                      "next_cursor": null,
                      "organizations": [
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000101",
                          "parent_id": "0a9e0000-0000-4000-8000-000000000100",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000101"
                          ],
                          "name": "Lakeside Clinic",
                          "description": "Family practice, two sites",
                          "rmm_client_id": "LAKESIDE-01",
                          "psa_client_id": "10042",
                          "created_at": "2026-11-02T09:00:00Z",
                          "updated_at": "2026-11-02T09:00:00Z",
                          "deleted_at": null
                        }
                      ],
                      "watermark": "2026-11-10T09:00:00Z"
                    }
                  },
                  "by-name": {
                    "summary": "Find a site by its name under its client, after a create whose answer was lost",
                    "value": {
                      "message": "organizations retrieved",
                      "next_cursor": null,
                      "organizations": [
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000102",
                          "parent_id": "0a9e0000-0000-4000-8000-000000000101",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000101",
                            "0a9e0000-0000-4000-8000-000000000102"
                          ],
                          "name": "Finance",
                          "description": null,
                          "rmm_client_id": null,
                          "psa_client_id": null,
                          "created_at": "2026-11-03T10:00:00Z",
                          "updated_at": "2026-11-03T10:00:00Z",
                          "deleted_at": null
                        }
                      ],
                      "watermark": "2026-11-10T09:00:00Z"
                    }
                  },
                  "psa-client-new": {
                    "summary": "Look up a PSA client id before creating its organization, deleted ones included",
                    "value": {
                      "message": "organizations retrieved",
                      "next_cursor": null,
                      "organizations": [],
                      "watermark": "2026-11-02T08:00:00Z"
                    }
                  },
                  "rmm-client-new": {
                    "summary": "Look up an RMM client id before creating its organization, deleted ones included",
                    "value": {
                      "message": "organizations retrieved",
                      "next_cursor": null,
                      "organizations": [],
                      "watermark": "2026-11-02T08:00:00Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, one given twice, or `fields` naming a field it does not have.\n`APP_API_ERR_BAD_PARAMETERS`: A filter's value is empty, names an empty item, is not one of the values the filter takes, or is not an id or a time where the filter asks for one; `parameter` names the filter.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `deleted` is not a value it takes, or `limit` is out of range, `cursor` cannot be read or was sent with other filters, or `updated_since` is not a valid time.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `organization.read`. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/organizations/client-id-check": {
      "post": {
        "operationId": "checkClientId",
        "tags": [
          "organizations"
        ],
        "summary": "Check a client id",
        "description": "Returns how many organizations in the workspace record an RMM or PSA client id, live and deleted, and which of them you can see. Send `rmm_client_id` or `psa_client_id`, not both. The counts include organizations you cannot see. It changes nothing.\n\nAccess: Needs any one of `organization.create` or `organization.write`. `organization.create` applies at each organization a grant covers and every organization below it. `organization.write` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400. An unknown body field returns 400.",
        "security": [
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "organization.create",
          "organization.write"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "rmm": {
                "summary": "Check whether an RMM client id is taken",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ClientIDCheck"
              },
              "examples": {
                "rmm": {
                  "summary": "Check whether an RMM client id is taken",
                  "value": {
                    "privilege_organization_id": "0a9e0000-0000-4000-8000-000000000101",
                    "rmm_client_id": "LAKESIDE-01"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Check a client id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientIDCheckResult"
                },
                "examples": {
                  "rmm": {
                    "summary": "Check whether an RMM client id is taken",
                    "value": {
                      "message": "client id checked",
                      "live_count": 1,
                      "deleted_count": 0,
                      "visible_matches": [
                        {
                          "id": "0a9e0000-0000-4000-8000-000000000101",
                          "name": "Lakeside Clinic",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000101"
                          ],
                          "deleted": false
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`.\n`APP_API_ERR_MISSING_PARAMETER`: Neither `rmm_client_id` nor `psa_client_id` is sent, or the one sent is empty.\n`APP_API_ERR_PARAMETER_TOO_LONG`: The client id is longer than 256 characters once cleaned.\n`APP_API_ERR_BAD_PARAMETERS`: Both `rmm_client_id` and `psa_client_id` are sent; `parameter` names `psa_client_id`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: You hold neither `organization.create` nor `organization.write` at `privilege_organization_id`. The same refusal comes when the path names a workspace other than the token's own.\n`APP_API_ERR_NO_PRIVILEGE_ON_ALL_ORGANIZATIONS`: There is no `privilege_organization_id` and you hold neither privilege over every organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/organizations/{id}": {
      "patch": {
        "operationId": "updateOrganization",
        "tags": [
          "organizations"
        ],
        "summary": "Update an organization",
        "description": "Changes an organization's name, description, client ids or custom fields; a field left out keeps its value. Needs `organization.write` at the organization. A deleted organization can be updated. To change its parent, move it.\n\nAccess: Needs `organization.write`. `organization.write` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400. An unknown body field returns 400.",
        "security": [
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "organization.write"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "client-ids": {
                "summary": "Record an organization's PSA client id",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "role-refused": {
                "summary": "A token whose scopes carry the privilege but whose grants do not hold it there",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The organization's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "client-ids": {
                "summary": "Record an organization's PSA client id",
                "value": "0a9e0000-0000-4000-8000-000000000103"
              },
              "role-refused": {
                "summary": "A token whose scopes carry the privilege but whose grants do not hold it there",
                "value": "0a9e0000-0000-4000-8000-000000000105"
              }
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrganizationUpdate"
              },
              "examples": {
                "client-ids": {
                  "summary": "Record an organization's PSA client id",
                  "value": {
                    "psa_client_id": "10063"
                  }
                },
                "role-refused": {
                  "summary": "A token whose scopes carry the privilege but whose grants do not hold it there",
                  "value": {
                    "name": "Harbor Dental Group"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update an organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IDResult"
                },
                "examples": {
                  "client-ids": {
                    "summary": "Record an organization's PSA client id",
                    "value": {
                      "message": "organization updated",
                      "id": "0a9e0000-0000-4000-8000-000000000103"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`.\n`APP_API_ERR_BAD_PARAMETERS`: `name` is empty, or the body names `parent_id`: move the organization instead.\n`APP_API_ERR_PARAMETER_TOO_LONG`: `name` is longer than 128 characters, `description` longer than 2048, or a client id longer than 256 characters once cleaned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: The object does not exist, is in another workspace or is outside your reach, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "role-refused": {
                    "summary": "A token whose scopes carry the privilege but whose grants do not hold it there",
                    "value": {
                      "at_org": true,
                      "cause": "no_privilege",
                      "error": "this credential does not have the privileges to perform this action on the organization 0a9e0000-0000-4000-8000-000000000105",
                      "error_code": "APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION",
                      "privilege": "organization.write"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteOrganization",
        "tags": [
          "organizations"
        ],
        "summary": "Delete an organization",
        "description": "Marks an organization deleted. It must be empty: no live agent or ingest key in it or below it, and no live organization below it. Needs `organization.delete` at the organization. Deleting a deleted organization changes nothing. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 2 hours.\n\nAccess: Needs `organization.delete`. `organization.delete` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400. A delete takes no body: its options are query parameters, and a body carrying anything returns 400.",
        "security": [
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "organization.delete"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "delete": {
                "summary": "Delete an empty organization",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "not-empty": {
                "summary": "An organization that still holds an agent, ingest key or organization",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "site": {
                "summary": "Delete a client's site",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "client": {
                "summary": "Delete a client's organization once nothing is left in it",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The organization's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "delete": {
                "summary": "Delete an empty organization",
                "value": "0a9e0000-0000-4000-8000-000000000104"
              },
              "not-empty": {
                "summary": "An organization that still holds an agent, ingest key or organization",
                "value": "0a9e0000-0000-4000-8000-000000000101"
              },
              "site": {
                "summary": "Delete a client's site",
                "value": "0a9e0000-0000-4000-8000-000000000102"
              },
              "client": {
                "summary": "Delete a client's organization once nothing is left in it",
                "value": "0a9e0000-0000-4000-8000-000000000101"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Delete an organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WriteResult"
                },
                "examples": {
                  "delete": {
                    "summary": "Delete an empty organization",
                    "value": {
                      "message": "organization deleted",
                      "cache_clear_status": "ok"
                    }
                  },
                  "site": {
                    "summary": "Delete a client's site",
                    "value": {
                      "message": "organization deleted",
                      "cache_clear_status": "ok"
                    }
                  },
                  "client": {
                    "summary": "Delete a client's organization once nothing is left in it",
                    "value": {
                      "message": "organization deleted",
                      "cache_clear_status": "ok"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, or one given twice.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The request carries a body other than nothing, `null` or `{}`: a delete takes none, and its options are query parameters; `parameter` names the body's first field, or `body`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: The object does not exist, is in another workspace or is outside your reach, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`APP_API_ERR_CANNOT_DELETE_ORG_NOT_EMPTY`: A live agent, ingest key or organization is in it or below it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not-empty": {
                    "summary": "An organization that still holds an agent, ingest key or organization",
                    "value": {
                      "error": "cannot delete organization because it is not empty: it still holds live agents, ingest keys or child organizations",
                      "error_code": "APP_API_ERR_CANNOT_DELETE_ORG_NOT_EMPTY"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "readOrganization",
        "tags": [
          "organizations"
        ],
        "summary": "Read an organization",
        "description": "Returns one organization you can see, deleted or not. One you cannot see returns 404, as one that does not exist does.\n\nAccess: Needs `organization.read`. `organization.read` applies at each organization a grant covers and every organization below it.\n\nFields sent by default: id, parent_id, path, name, description, rmm_client_id, psa_client_id, created_at, updated_at, deleted_at. Heavy, sent only when named: custom_fields.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": [
              "workspace:read"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "organization.read"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "read": {
                "summary": "Read an organization",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The organization's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "read": {
                "summary": "Read an organization",
                "value": "0a9e0000-0000-4000-8000-000000000102"
              }
            }
          },
          {
            "name": "fields",
            "in": "query",
            "description": "Comma-separated top-level fields of each object to return instead of the default set.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false
          }
        ],
        "responses": {
          "200": {
            "description": "Read an organization",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "organization": {
                      "$ref": "#/components/schemas/Organization",
                      "description": "The organization."
                    },
                    "message": {
                      "type": "string",
                      "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
                    }
                  },
                  "required": [
                    "organization",
                    "message"
                  ]
                },
                "examples": {
                  "read": {
                    "summary": "Read an organization",
                    "value": {
                      "message": "organization retrieved",
                      "organization": {
                        "id": "0a9e0000-0000-4000-8000-000000000102",
                        "parent_id": "0a9e0000-0000-4000-8000-000000000101",
                        "path": [
                          "0a9e0000-0000-4000-8000-000000000100",
                          "0a9e0000-0000-4000-8000-000000000101",
                          "0a9e0000-0000-4000-8000-000000000102"
                        ],
                        "name": "Finance",
                        "description": null,
                        "rmm_client_id": null,
                        "psa_client_id": null,
                        "created_at": "2026-11-03T10:00:00Z",
                        "updated_at": "2026-11-03T10:00:00Z",
                        "deleted_at": null
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, one given twice, or `fields` naming a field it does not have.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `organization.read`. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`APP_API_ERR_RECORD_NOT_FOUND`: No such organization, or one you cannot see.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/organizations/{id}/move": {
      "post": {
        "operationId": "moveOrganization",
        "tags": [
          "organizations"
        ],
        "summary": "Move an organization",
        "description": "Moves an organization, with everything below it, under `parent_id`. Needs `organization.move` at its current parent, or over every organization for a top-level one, and at the new parent. An organization cannot move under itself or anything below it, and a live one cannot move under a deleted one. Another move that lands while this one runs makes it return 400 naming `parent_id`: read the tree again before choosing. An organization created while it runs makes it return 409: send the same call again. Neither moves anything. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 2 hours.\n\nAccess: Needs `organization.move` at the organization it is in now and `organization.move` at the organization it moves to. `organization.move` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400. An unknown body field returns 400.",
        "security": [
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "organization.move"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "move": {
                "summary": "Move Finance under Oakridge Medical",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The organization's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "move": {
                "summary": "Move Finance under Oakridge Medical",
                "value": "0a9e0000-0000-4000-8000-000000000102"
              }
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrganizationMove"
              },
              "examples": {
                "move": {
                  "summary": "Move Finance under Oakridge Medical",
                  "value": {
                    "parent_id": "0a9e0000-0000-4000-8000-000000000103"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Move an organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WriteResult"
                },
                "examples": {
                  "move": {
                    "summary": "Move Finance under Oakridge Medical",
                    "value": {
                      "message": "organization moved",
                      "cache_clear_status": "ok"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`.\n`APP_API_ERR_MISSING_PARAMETER`: `parent_id` is left out.\n`APP_API_ERR_BAD_PARAMETERS`: `parent_id` is not a UUID, is the organization itself or below it, is deleted while the organization is live, or would make the tree deeper than 25 levels.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: The organization or the new parent does not exist or is outside your reach, or you do not hold `organization.move` at the organization's parent and at the new one. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`APP_API_ERR_CONFLICT`: Another move landed after this call read the tree, and the organization is no longer where the call read it or the new place now breaks one of the rules above; or an organization created in the workspace while the move ran collided with it. Nothing moved: read the organizations again before sending it again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/organizations/{id}/restore": {
      "post": {
        "operationId": "restoreOrganization",
        "tags": [
          "organizations"
        ],
        "summary": "Restore a deleted organization",
        "description": "Restores a deleted organization whose parent is live. Needs `organization.delete` at the organization. Restoring a live organization changes nothing. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 2 hours.\n\nAccess: Needs `organization.delete`. `organization.delete` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400. It takes no body: a body field returns 400.",
        "security": [
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "organization.delete"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "restore": {
                "summary": "Restore a deleted organization",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The organization's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "restore": {
                "summary": "Restore a deleted organization",
                "value": "0a9e0000-0000-4000-8000-000000000104"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Restore a deleted organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WriteResult"
                },
                "examples": {
                  "restore": {
                    "summary": "Restore a deleted organization",
                    "value": {
                      "message": "organization restored",
                      "cache_clear_status": "ok"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, or names a field: the call takes none.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: The object does not exist, is in another workspace or is outside your reach, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`APP_API_ERR_CANNOT_RESTORE_PARENT_DELETED`: Its parent is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/registration-tokens": {
      "post": {
        "operationId": "createRegistrationToken",
        "tags": [
          "registration-tokens"
        ],
        "summary": "Create a registration token",
        "description": "Creates a token that agent installers present to register into `organization_id` or an organization below it, and returns it. Needs `registration_token.create` at that organization. An install that passes an RMM or PSA client id lands in the organization at or below `organization_id` that records that id, ignoring case, a live one before a deleted one, and fails when the best match is deleted. With no match it creates a new organization directly under `organization_id`, named from the install's client name, so record the id your RMM passes on the client's organization before deploying.\n\nAccess: Needs `registration_token.create`. `registration_token.create` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400. An unknown body field returns 400.\n\nSecret: The response carries a secret and is sent with `Cache-Control: no-store`. Keep it out of caches and logs.",
        "security": [
          {
            "bearer": [
              "fleet:deploy"
            ]
          },
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "registration_token.create"
        ],
        "x-returns-secret": true,
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "lakeside": {
                "summary": "Create a registration token for Lakeside Clinic",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "replacement": {
                "summary": "Create a registration token to replace one that expires soon",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegistrationTokenCreate"
              },
              "examples": {
                "lakeside": {
                  "summary": "Create a registration token for Lakeside Clinic",
                  "value": {
                    "expires_at": "2026-11-30T00:00:00Z",
                    "label": "Lakeside Clinic rollout",
                    "organization_id": "0a9e0000-0000-4000-8000-000000000101"
                  }
                },
                "replacement": {
                  "summary": "Create a registration token to replace one that expires soon",
                  "value": {
                    "expires_at": "2026-12-30T00:00:00Z",
                    "label": "Lakeside Clinic rollout, December",
                    "organization_id": "0a9e0000-0000-4000-8000-000000000101"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Create a registration token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegistrationTokenCreated"
                },
                "examples": {
                  "lakeside": {
                    "summary": "Create a registration token for Lakeside Clinic",
                    "value": {
                      "message": "registration token created",
                      "id": "7e0c0000-0000-4000-8000-000000000301",
                      "token": "EXAMPLE-REGISTRATION-TOKEN-NOT-REAL"
                    }
                  },
                  "replacement": {
                    "summary": "Create a registration token to replace one that expires soon",
                    "value": {
                      "message": "registration token created",
                      "id": "7e0c0000-0000-4000-8000-000000000302",
                      "token": "EXAMPLE-NEW-REGISTRATION-TOKEN-NOT-REAL"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`.\n`APP_API_ERR_MISSING_PARAMETER`: `organization_id` is left out.\n`APP_API_ERR_BAD_PARAMETERS`: `organization_id` is not a UUID or names a deleted organization, or `expires_at` is not a valid time.\n`APP_API_ERR_PARAMETER_TOO_LONG`: `label` is longer than 256 characters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: You do not hold `registration_token.create` at `organization_id`, or it names no organization you can see. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listRegistrationTokens",
        "tags": [
          "registration-tokens"
        ],
        "summary": "List registration tokens",
        "description": "Returns the registration tokens you can see, a page at a time, in `id` order, or least recently changed first with `updated_since`, never with their secrets. Seeing a token takes `organization.read` and `registration_token.read` at its organization. Filter by organization, with or without the organizations below it, by `status` and by `label`; filters combine, a row passing every one given. `status` is worked out at the walk's `as_of`, the same instant for every page, and a token passing its `expires_at` does not change its `updated_at`, so a sync from `updated_since` misses it: find expired tokens on a full walk. `deleted=include` or `deleted=only` returns deleted tokens, and tokens of deleted organizations, too.\n\nAccess: Needs `registration_token.read`. `registration_token.read` applies at each organization a grant covers and every organization below it. A caller who reaches no organization gets an empty list.\n\nFields sent by default: id, organization_id, path, label, status, created_by_user_id, expires_at, revoked_at, revocation_reason, use_count, last_used_at, created_at, updated_at, deleted_at.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": [
              "fleet:deploy"
            ]
          },
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "registration_token.read"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "active": {
                "summary": "List the active registration tokens",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "by-label": {
                "summary": "Find Lakeside Clinic's active rollout token by its label",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "clients-by-label": {
                "summary": "Find the token at the organization holding your clients by its label",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "client-active": {
                "summary": "List the active registration tokens of Lakeside Clinic and below",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "organization_id",
            "in": "query",
            "description": "Only tokens of this organization.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "by-label": {
                "summary": "Find Lakeside Clinic's active rollout token by its label",
                "value": "0a9e0000-0000-4000-8000-000000000101"
              },
              "clients-by-label": {
                "summary": "Find the token at the organization holding your clients by its label",
                "value": "0a9e0000-0000-4000-8000-000000000100"
              },
              "client-active": {
                "summary": "List the active registration tokens of Lakeside Clinic and below",
                "value": "0a9e0000-0000-4000-8000-000000000101"
              }
            }
          },
          {
            "name": "subtree",
            "in": "query",
            "description": "`true` adds the tokens of every organization below `organization_id`. `true` and `false` are the only values it takes.",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "examples": {
              "client-active": {
                "summary": "List the active registration tokens of Lakeside Clinic and below",
                "value": true
              }
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Only the tokens with these ids. A comma-separated list of at most 100 ids matches any of them.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false,
            "x-filter": {
              "kind": "in",
              "clock": false,
              "with_updated_since": true
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Only tokens whose `status` is one of these. A comma-separated list matches any of its values. Worked out at the walk's `as_of`, so a row can start or stop matching without changing: use it on a full walk, never with `updated_since`.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "active",
                  "revoked",
                  "expired"
                ]
              }
            },
            "style": "form",
            "explode": false,
            "x-filter": {
              "kind": "in",
              "clock": true,
              "with_updated_since": false
            },
            "examples": {
              "active": {
                "summary": "List the active registration tokens",
                "value": [
                  "active"
                ]
              },
              "by-label": {
                "summary": "Find Lakeside Clinic's active rollout token by its label",
                "value": [
                  "active"
                ]
              },
              "clients-by-label": {
                "summary": "Find the token at the organization holding your clients by its label",
                "value": [
                  "active"
                ]
              },
              "client-active": {
                "summary": "List the active registration tokens of Lakeside Clinic and below",
                "value": [
                  "active"
                ]
              }
            }
          },
          {
            "name": "label",
            "in": "query",
            "description": "Only tokens of this label: the way to find a token created by a call whose answer was lost. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.",
            "schema": {
              "type": "string"
            },
            "x-filter": {
              "kind": "eq_fold",
              "clock": false,
              "with_updated_since": true
            },
            "examples": {
              "by-label": {
                "summary": "Find Lakeside Clinic's active rollout token by its label",
                "value": "Lakeside Clinic rollout"
              },
              "clients-by-label": {
                "summary": "Find the token at the organization holding your clients by its label",
                "value": "Northwind clients agents"
              }
            }
          },
          {
            "name": "deleted",
            "in": "query",
            "description": "Which tokens to list, by whether they or their organization are deleted.",
            "schema": {
              "type": "string",
              "enum": [
                "exclude",
                "include",
                "only"
              ],
              "default": "exclude"
            }
          },
          {
            "name": "updated_since",
            "in": "query",
            "description": "Only tokens changed at or after this time (RFC 3339). Pass the watermark of your last complete sync.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "How many tokens a page holds: 1 to 5000, 1000 by default.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 5000
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "The `next_cursor` of the previous page, with the same filters.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "description": "Comma-separated top-level fields of each object to return instead of the default set.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false
          }
        ],
        "responses": {
          "200": {
            "description": "List registration tokens",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "registration_tokens": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/RegistrationToken"
                      },
                      "description": "The registration tokens on this page."
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Null on the last page. Otherwise pass it as `cursor` for the next page."
                    },
                    "watermark": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Pass it as `updated_since` on your next sync."
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time",
                      "description": "The instant this walk's values worked out from the clock, and its filters on them, are worked out at: fixed on the first page and the same on every page after it."
                    },
                    "message": {
                      "type": "string",
                      "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
                    }
                  },
                  "required": [
                    "registration_tokens",
                    "next_cursor",
                    "watermark",
                    "as_of",
                    "message"
                  ]
                },
                "examples": {
                  "active": {
                    "summary": "List the active registration tokens",
                    "value": {
                      "as_of": "2026-11-10T09:01:00Z",
                      "message": "registration tokens retrieved",
                      "next_cursor": null,
                      "registration_tokens": [
                        {
                          "id": "7e0c0000-0000-4000-8000-000000000301",
                          "organization_id": "0a9e0000-0000-4000-8000-000000000101",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000101",
                            "7e0c0000-0000-4000-8000-000000000301"
                          ],
                          "label": "Lakeside Clinic rollout",
                          "status": "active",
                          "created_by_user_id": "AlexRiveraExampleUserId00001",
                          "expires_at": "2026-11-30T00:00:00Z",
                          "revoked_at": null,
                          "revocation_reason": null,
                          "use_count": 1,
                          "last_used_at": "2026-11-03T12:00:00Z",
                          "created_at": "2026-11-03T11:00:00Z",
                          "updated_at": "2026-11-03T12:00:00Z",
                          "deleted_at": null
                        },
                        {
                          "id": "7e0c0000-0000-4000-8000-000000000303",
                          "organization_id": "0a9e0000-0000-4000-8000-000000000100",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "7e0c0000-0000-4000-8000-000000000303"
                          ],
                          "label": "Northwind clients agents",
                          "status": "active",
                          "created_by_user_id": "AlexRiveraExampleUserId00001",
                          "expires_at": null,
                          "revoked_at": null,
                          "revocation_reason": null,
                          "use_count": 1,
                          "last_used_at": "2026-11-04T09:00:00Z",
                          "created_at": "2026-11-01T10:00:00Z",
                          "updated_at": "2026-11-04T09:00:00Z",
                          "deleted_at": null
                        }
                      ],
                      "watermark": "2026-11-10T09:00:00Z"
                    }
                  },
                  "by-label": {
                    "summary": "Find Lakeside Clinic's active rollout token by its label",
                    "value": {
                      "as_of": "2026-11-10T09:01:00Z",
                      "message": "registration tokens retrieved",
                      "next_cursor": null,
                      "registration_tokens": [
                        {
                          "id": "7e0c0000-0000-4000-8000-000000000301",
                          "organization_id": "0a9e0000-0000-4000-8000-000000000101",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000101",
                            "7e0c0000-0000-4000-8000-000000000301"
                          ],
                          "label": "Lakeside Clinic rollout",
                          "status": "active",
                          "created_by_user_id": "AlexRiveraExampleUserId00001",
                          "expires_at": "2026-11-30T00:00:00Z",
                          "revoked_at": null,
                          "revocation_reason": null,
                          "use_count": 1,
                          "last_used_at": "2026-11-03T12:00:00Z",
                          "created_at": "2026-11-03T11:00:00Z",
                          "updated_at": "2026-11-03T12:00:00Z",
                          "deleted_at": null
                        }
                      ],
                      "watermark": "2026-11-10T09:00:00Z"
                    }
                  },
                  "clients-by-label": {
                    "summary": "Find the token at the organization holding your clients by its label",
                    "value": {
                      "as_of": "2026-11-10T09:01:00Z",
                      "message": "registration tokens retrieved",
                      "next_cursor": null,
                      "registration_tokens": [
                        {
                          "id": "7e0c0000-0000-4000-8000-000000000303",
                          "organization_id": "0a9e0000-0000-4000-8000-000000000100",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "7e0c0000-0000-4000-8000-000000000303"
                          ],
                          "label": "Northwind clients agents",
                          "status": "active",
                          "created_by_user_id": "AlexRiveraExampleUserId00001",
                          "expires_at": null,
                          "revoked_at": null,
                          "revocation_reason": null,
                          "use_count": 1,
                          "last_used_at": "2026-11-04T09:00:00Z",
                          "created_at": "2026-11-01T10:00:00Z",
                          "updated_at": "2026-11-04T09:00:00Z",
                          "deleted_at": null
                        }
                      ],
                      "watermark": "2026-11-10T09:00:00Z"
                    }
                  },
                  "client-active": {
                    "summary": "List the active registration tokens of Lakeside Clinic and below",
                    "value": {
                      "as_of": "2026-11-10T09:01:00Z",
                      "message": "registration tokens retrieved",
                      "next_cursor": null,
                      "registration_tokens": [
                        {
                          "id": "7e0c0000-0000-4000-8000-000000000301",
                          "organization_id": "0a9e0000-0000-4000-8000-000000000101",
                          "path": [
                            "0a9e0000-0000-4000-8000-000000000100",
                            "0a9e0000-0000-4000-8000-000000000101",
                            "7e0c0000-0000-4000-8000-000000000301"
                          ],
                          "label": "Lakeside Clinic rollout",
                          "status": "active",
                          "created_by_user_id": "AlexRiveraExampleUserId00001",
                          "expires_at": "2026-11-30T00:00:00Z",
                          "revoked_at": null,
                          "revocation_reason": null,
                          "use_count": 1,
                          "last_used_at": "2026-11-03T12:00:00Z",
                          "created_at": "2026-11-03T11:00:00Z",
                          "updated_at": "2026-11-03T12:00:00Z",
                          "deleted_at": null
                        }
                      ],
                      "watermark": "2026-11-10T09:00:00Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, one given twice, or `fields` naming a field it does not have.\n`APP_API_ERR_BAD_PARAMETERS`: A filter's value is empty, names an empty item, is not one of the values the filter takes, or is not an id or a time where the filter asks for one; `parameter` names the filter.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `organization_id` is not a UUID, `subtree` is neither `true` nor `false` or comes without it, `deleted` is not a value it takes, or `limit` is out of range, `cursor` cannot be read or was sent with other filters, or `updated_since` is not a valid time.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `organization.read` and `registration_token.read`. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/registration-tokens/{id}": {
      "patch": {
        "operationId": "updateRegistrationToken",
        "tags": [
          "registration-tokens"
        ],
        "summary": "Update a registration token",
        "description": "Changes a registration token's label or expiry; a field left out keeps its value, and an `expires_at` of null removes the expiry. Moving `expires_at` later, or to null, makes an expired token active again with the same secret; a revoked token stays revoked. Needs `registration_token.revoke` at the token's organization.\n\nAccess: Needs `registration_token.revoke`. `registration_token.revoke` applies at each organization a grant covers and every organization below it. `registration_token.revoke` also admits updating, deleting and restoring a registration token, not only revoking it.\n\nUnknown input: An unknown or repeated query parameter returns 400. An unknown body field returns 400.",
        "security": [
          {
            "bearer": [
              "fleet:deploy"
            ]
          },
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "registration_token.revoke"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "rename": {
                "summary": "Rename a registration token",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "no-expiry": {
                "summary": "Remove a registration token's expiry",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The registration token's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "rename": {
                "summary": "Rename a registration token",
                "value": "7e0c0000-0000-4000-8000-000000000301"
              },
              "no-expiry": {
                "summary": "Remove a registration token's expiry",
                "value": "7e0c0000-0000-4000-8000-000000000301"
              }
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegistrationTokenUpdate"
              },
              "examples": {
                "rename": {
                  "summary": "Rename a registration token",
                  "value": {
                    "label": "Lakeside Clinic, all sites"
                  }
                },
                "no-expiry": {
                  "summary": "Remove a registration token's expiry",
                  "value": {
                    "expires_at": null
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update a registration token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IDResult"
                },
                "examples": {
                  "rename": {
                    "summary": "Rename a registration token",
                    "value": {
                      "message": "registration token updated",
                      "id": "7e0c0000-0000-4000-8000-000000000301"
                    }
                  },
                  "no-expiry": {
                    "summary": "Remove a registration token's expiry",
                    "value": {
                      "message": "registration token updated",
                      "id": "7e0c0000-0000-4000-8000-000000000301"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`.\n`APP_API_ERR_BAD_PARAMETERS`: `expires_at` is not a valid time.\n`APP_API_ERR_PARAMETER_TOO_LONG`: `label` is longer than 256 characters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: The object does not exist, is in another workspace or is outside your reach, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`APP_API_ERR_CONFLICT`: The token is deleted: restore it first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteRegistrationToken",
        "tags": [
          "registration-tokens"
        ],
        "summary": "Delete a registration token",
        "description": "Marks a registration token deleted. Needs `registration_token.revoke` at the token's organization. Deleting a deleted token changes nothing.\n\nAccess: Needs `registration_token.revoke`. `registration_token.revoke` applies at each organization a grant covers and every organization below it. `registration_token.revoke` also admits updating, deleting and restoring a registration token, not only revoking it.\n\nUnknown input: An unknown or repeated query parameter returns 400. A delete takes no body: its options are query parameters, and a body carrying anything returns 400.",
        "security": [
          {
            "bearer": [
              "fleet:deploy"
            ]
          },
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "registration_token.revoke"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "delete": {
                "summary": "Delete a registration token",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The registration token's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "delete": {
                "summary": "Delete a registration token",
                "value": "7e0c0000-0000-4000-8000-000000000301"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Delete a registration token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WriteResult"
                },
                "examples": {
                  "delete": {
                    "summary": "Delete a registration token",
                    "value": {
                      "message": "registration token deleted"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, or one given twice.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The request carries a body other than nothing, `null` or `{}`: a delete takes none, and its options are query parameters; `parameter` names the body's first field, or `body`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: The object does not exist, is in another workspace or is outside your reach, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "readRegistrationToken",
        "tags": [
          "registration-tokens"
        ],
        "summary": "Read a registration token",
        "description": "Returns one registration token you can see, deleted or not, without its secret. One you cannot see returns 404, as one that does not exist does.\n\nAccess: Needs `registration_token.read`. `registration_token.read` applies at each organization a grant covers and every organization below it.\n\nFields sent by default: id, organization_id, path, label, status, created_by_user_id, expires_at, revoked_at, revocation_reason, use_count, last_used_at, created_at, updated_at, deleted_at.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": [
              "fleet:deploy"
            ]
          },
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "registration_token.read"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "read": {
                "summary": "Read a registration token",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "replacement": {
                "summary": "Read the registration token that replaced another",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The registration token's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "read": {
                "summary": "Read a registration token",
                "value": "7e0c0000-0000-4000-8000-000000000301"
              },
              "replacement": {
                "summary": "Read the registration token that replaced another",
                "value": "7e0c0000-0000-4000-8000-000000000302"
              }
            }
          },
          {
            "name": "fields",
            "in": "query",
            "description": "Comma-separated top-level fields of each object to return instead of the default set.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false
          }
        ],
        "responses": {
          "200": {
            "description": "Read a registration token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "registration_token": {
                      "$ref": "#/components/schemas/RegistrationToken",
                      "description": "The registration token."
                    },
                    "message": {
                      "type": "string",
                      "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
                    }
                  },
                  "required": [
                    "registration_token",
                    "message"
                  ]
                },
                "examples": {
                  "read": {
                    "summary": "Read a registration token",
                    "value": {
                      "message": "registration token retrieved",
                      "registration_token": {
                        "id": "7e0c0000-0000-4000-8000-000000000301",
                        "organization_id": "0a9e0000-0000-4000-8000-000000000101",
                        "path": [
                          "0a9e0000-0000-4000-8000-000000000100",
                          "0a9e0000-0000-4000-8000-000000000101",
                          "7e0c0000-0000-4000-8000-000000000301"
                        ],
                        "label": "Lakeside Clinic rollout",
                        "status": "active",
                        "created_by_user_id": "AlexRiveraExampleUserId00001",
                        "expires_at": "2026-11-30T00:00:00Z",
                        "revoked_at": null,
                        "revocation_reason": null,
                        "use_count": 1,
                        "last_used_at": "2026-11-03T12:00:00Z",
                        "created_at": "2026-11-03T11:00:00Z",
                        "updated_at": "2026-11-03T12:00:00Z",
                        "deleted_at": null
                      }
                    }
                  },
                  "replacement": {
                    "summary": "Read the registration token that replaced another",
                    "value": {
                      "message": "registration token retrieved",
                      "registration_token": {
                        "id": "7e0c0000-0000-4000-8000-000000000302",
                        "organization_id": "0a9e0000-0000-4000-8000-000000000101",
                        "path": [
                          "0a9e0000-0000-4000-8000-000000000100",
                          "0a9e0000-0000-4000-8000-000000000101",
                          "7e0c0000-0000-4000-8000-000000000302"
                        ],
                        "label": "Lakeside Clinic rollout, December",
                        "status": "active",
                        "created_by_user_id": null,
                        "expires_at": "2026-12-30T00:00:00Z",
                        "revoked_at": null,
                        "revocation_reason": null,
                        "use_count": 0,
                        "last_used_at": null,
                        "created_at": "2026-11-10T11:00:00Z",
                        "updated_at": "2026-11-10T11:00:00Z",
                        "deleted_at": null
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, one given twice, or `fields` naming a field it does not have.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `organization.read` and `registration_token.read`. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "`APP_API_ERR_RECORD_NOT_FOUND`: No such registration token, or one you cannot see.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/registration-tokens/{id}/restore": {
      "post": {
        "operationId": "restoreRegistrationToken",
        "tags": [
          "registration-tokens"
        ],
        "summary": "Restore a deleted registration token",
        "description": "Restores a deleted registration token; a revoked or expired token stays so. Needs `registration_token.revoke` at the token's organization. Restoring a live one changes nothing.\n\nAccess: Needs `registration_token.revoke`. `registration_token.revoke` applies at each organization a grant covers and every organization below it. `registration_token.revoke` also admits updating, deleting and restoring a registration token, not only revoking it.\n\nUnknown input: An unknown or repeated query parameter returns 400. It takes no body: a body field returns 400.",
        "security": [
          {
            "bearer": [
              "fleet:deploy"
            ]
          },
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "registration_token.revoke"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "restore": {
                "summary": "Restore a deleted registration token",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The registration token's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "restore": {
                "summary": "Restore a deleted registration token",
                "value": "7e0c0000-0000-4000-8000-000000000301"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Restore a deleted registration token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WriteResult"
                },
                "examples": {
                  "restore": {
                    "summary": "Restore a deleted registration token",
                    "value": {
                      "message": "registration token restored"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, or names a field: the call takes none.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: The object does not exist, is in another workspace or is outside your reach, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/registration-tokens/{id}/revoke": {
      "post": {
        "operationId": "revokeRegistrationToken",
        "tags": [
          "registration-tokens"
        ],
        "summary": "Revoke a registration token",
        "description": "Revokes a registration token: agents can no longer register with it, and agents already registered keep working. Revoking cannot be undone. Needs `registration_token.revoke` at the token's organization. Revoking a revoked token changes nothing.\n\nAccess: Needs `registration_token.revoke`. `registration_token.revoke` applies at each organization a grant covers and every organization below it. `registration_token.revoke` also admits updating, deleting and restoring a registration token, not only revoking it.\n\nUnknown input: An unknown or repeated query parameter returns 400. An unknown body field returns 400.",
        "security": [
          {
            "bearer": [
              "fleet:deploy"
            ]
          },
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "registration_token.revoke"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "revoke": {
                "summary": "Revoke a registration token once the rollout is done",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "offboard": {
                "summary": "Revoke an offboarded client's registration token",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "replaced": {
                "summary": "Revoke a registration token a newer one replaced",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The registration token's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "revoke": {
                "summary": "Revoke a registration token once the rollout is done",
                "value": "7e0c0000-0000-4000-8000-000000000301"
              },
              "offboard": {
                "summary": "Revoke an offboarded client's registration token",
                "value": "7e0c0000-0000-4000-8000-000000000301"
              },
              "replaced": {
                "summary": "Revoke a registration token a newer one replaced",
                "value": "7e0c0000-0000-4000-8000-000000000301"
              }
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegistrationTokenRevoke"
              },
              "examples": {
                "revoke": {
                  "summary": "Revoke a registration token once the rollout is done",
                  "value": {
                    "reason": "Rollout finished"
                  }
                },
                "offboard": {
                  "summary": "Revoke an offboarded client's registration token",
                  "value": {
                    "reason": "Client offboarded"
                  }
                },
                "replaced": {
                  "summary": "Revoke a registration token a newer one replaced",
                  "value": {
                    "reason": "Replaced by a newer token"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Revoke a registration token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WriteResult"
                },
                "examples": {
                  "revoke": {
                    "summary": "Revoke a registration token once the rollout is done",
                    "value": {
                      "message": "registration token revoked"
                    }
                  },
                  "offboard": {
                    "summary": "Revoke an offboarded client's registration token",
                    "value": {
                      "message": "registration token revoked"
                    }
                  },
                  "replaced": {
                    "summary": "Revoke a registration token a newer one replaced",
                    "value": {
                      "message": "registration token revoked"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: The URL carries a query parameter, which a write does not take: its fields come from its body.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`.\n`APP_API_ERR_PARAMETER_TOO_LONG`: `reason` is longer than 1024 characters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: The object does not exist, is in another workspace or is outside your reach, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`APP_API_ERR_CONFLICT`: The token is deleted: restore it first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`APP_API_ERR_BODY_TOO_LARGE`: The body is larger than 1 MiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/registration-tokens/{id}/secret": {
      "get": {
        "operationId": "revealRegistrationToken",
        "tags": [
          "registration-tokens"
        ],
        "summary": "Read a registration token's secret",
        "description": "Returns the token agent installers present. Needs `registration_token.reveal` at the token's organization. Every call is recorded in the audit log. A deleted token returns 404.\n\nAccess: Needs `registration_token.reveal`. `registration_token.reveal` applies at each organization a grant covers and every organization below it.\n\nUnknown input: An unknown or repeated query parameter returns 400.\n\nSecret: The response carries a secret and is sent with `Cache-Control: no-store`. Keep it out of caches and logs.",
        "security": [
          {
            "bearer": [
              "fleet:deploy"
            ]
          },
          {
            "bearer": [
              "fleet:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "registration_token.reveal"
        ],
        "x-returns-secret": true,
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "read": {
                "summary": "Read a registration token's secret",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "clients": {
                "summary": "Read the secret of the token for every client",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The registration token's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "read": {
                "summary": "Read a registration token's secret",
                "value": "7e0c0000-0000-4000-8000-000000000301"
              },
              "clients": {
                "summary": "Read the secret of the token for every client",
                "value": "7e0c0000-0000-4000-8000-000000000303"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Read a registration token's secret",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegistrationTokenSecret"
                },
                "examples": {
                  "read": {
                    "summary": "Read a registration token's secret",
                    "value": {
                      "message": "registration token retrieved",
                      "token": "EXAMPLE-REGISTRATION-TOKEN-NOT-REAL"
                    }
                  },
                  "clients": {
                    "summary": "Read the secret of the token for every client",
                    "value": {
                      "message": "registration token retrieved",
                      "token": "EXAMPLE-CLIENTS-REGISTRATION-TOKEN-NOT-REAL"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, or one given twice.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.\n`APP_API_ERR_BAD_PARAMETERS`: `id` is not a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION`: The object does not exist, is in another workspace or is outside your reach, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`APP_API_ERR_CONFLICT`: The token is deleted: restore it first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/replication-targets": {
      "get": {
        "operationId": "listReplicationTargets",
        "tags": [
          "replication-targets"
        ],
        "summary": "List replication targets",
        "description": "Returns the workspace's replication targets you can see, in id order: where each copies data, its storage settings, which credentials it stores and how its latest run went. Needs `archive.config.read`: held over every organization, it lists every target; held at some organizations, it lists the targets that name one of them. A target's organizations are cut to those you can see. Credentials are named, never sent.\n\nAccess: Needs `archive.config.read`. `archive.config.read` applies at each organization a grant covers and every organization below it. A caller who reaches no organization gets an empty list.\n\nFields sent by default: id, target_type, name, description, enabled, scope, config, credential_names, job_status.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": [
              "admin:read"
            ]
          },
          {
            "bearer": [
              "admin:write"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "archive.config.read"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "list": {
                "summary": "List the replication targets",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "fields",
            "in": "query",
            "description": "Comma-separated top-level fields of each object to return instead of the default set.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false
          }
        ],
        "responses": {
          "200": {
            "description": "List replication targets",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "replication_targets": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ReplicationTarget"
                      },
                      "description": "Every one of the replication targets you can see."
                    },
                    "message": {
                      "type": "string",
                      "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
                    }
                  },
                  "required": [
                    "replication_targets",
                    "message"
                  ]
                },
                "examples": {
                  "list": {
                    "summary": "List the replication targets",
                    "value": {
                      "message": "replication targets retrieved",
                      "replication_targets": [
                        {
                          "id": "offsite-copy",
                          "target_type": "s3",
                          "name": "Offsite copy",
                          "description": "Nightly copy to the MSP's own bucket",
                          "enabled": true,
                          "scope": {
                            "kind": "all",
                            "org_ids": [],
                            "inherited": false,
                            "other_orgs": false
                          },
                          "config": {
                            "bucket": "northwind-archive",
                            "s3_region": "us-east-2"
                          },
                          "credential_names": [
                            "s3_access_key_id",
                            "s3_secret_access_key"
                          ],
                          "job_status": null
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, one given twice, or `fields` naming a field it does not have.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `archive.config.read`. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspace_id}/roles": {
      "get": {
        "operationId": "listRoles",
        "tags": [
          "roles"
        ],
        "summary": "List roles",
        "description": "Returns every role a grant in the workspace can name, the standard roles and the workspace's own, each with its privileges, in sort order.\n\nAccess: Needs `workspace.read`. Any grant in the workspace carries `workspace.read`.\n\nFields sent by default: id, kind, description, recommended_scope, sort_order, privileges.\n\nUnknown input: An unknown or repeated query parameter returns 400.",
        "security": [
          {
            "bearer": [
              "workspace:read"
            ]
          }
        ],
        "x-stability": "preview",
        "x-credentials": [
          "session",
          "user_key",
          "oauth",
          "workspace_key"
        ],
        "x-privileges": [
          "workspace.read"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "description": "The workspace's id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "examples": {
              "list": {
                "summary": "List the roles a grant can give, with their privileges",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              },
              "without-privileges": {
                "summary": "List the roles a grant can give, without their privileges",
                "value": "5e1f0a00-0000-4000-8000-000000000001"
              }
            }
          },
          {
            "name": "fields",
            "in": "query",
            "description": "Comma-separated top-level fields of each object to return instead of the default set.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": false,
            "examples": {
              "without-privileges": {
                "summary": "List the roles a grant can give, without their privileges",
                "value": [
                  "id",
                  "kind",
                  "description",
                  "recommended_scope",
                  "sort_order"
                ]
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List roles",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "roles": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Role"
                      },
                      "description": "Every one of the roles you can see."
                    },
                    "message": {
                      "type": "string",
                      "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
                    }
                  },
                  "required": [
                    "roles",
                    "message"
                  ]
                },
                "examples": {
                  "list": {
                    "summary": "List the roles a grant can give, with their privileges",
                    "value": {
                      "message": "roles retrieved",
                      "roles": [
                        {
                          "id": "admin",
                          "kind": "standard",
                          "description": "Administrator with rights to everything, including managing users in the workspace and their roles",
                          "recommended_scope": "all",
                          "sort_order": 10,
                          "privileges": [
                            {
                              "id": "workspace.read",
                              "level": "self",
                              "category": null,
                              "access_kind": "view"
                            },
                            {
                              "id": "workspace.write",
                              "level": "workspace",
                              "category": "organizations",
                              "access_kind": "manage"
                            },
                            {
                              "id": "member.read",
                              "level": "org",
                              "category": "people",
                              "access_kind": "view"
                            },
                            {
                              "id": "member.manage",
                              "level": "org",
                              "category": "people",
                              "access_kind": "manage"
                            },
                            {
                              "id": "group.read",
                              "level": "org",
                              "category": "people",
                              "access_kind": "view"
                            },
                            {
                              "id": "group.write",
                              "level": "org",
                              "category": "people",
                              "access_kind": "manage"
                            },
                            {
                              "id": "grant.write",
                              "level": "org",
                              "category": "people",
                              "access_kind": "manage"
                            },
                            {
                              "id": "auditlog.query",
                              "level": "org",
                              "category": "activity_log",
                              "access_kind": "view"
                            },
                            {
                              "id": "organization.read",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "view"
                            },
                            {
                              "id": "organization.create",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "manage"
                            },
                            {
                              "id": "organization.write",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "manage"
                            },
                            {
                              "id": "organization.move",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "manage"
                            },
                            {
                              "id": "organization.delete",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "manage"
                            },
                            {
                              "id": "agent.read",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "view"
                            },
                            {
                              "id": "agent.write",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "agent.delete",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "agent_policy.write",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "agent_policy.assign",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "agent_policy.rule_write",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "agent_policy.enforce",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "agent_tag.define",
                              "level": "workspace",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "agent_tag.attach",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "ingest_key.create",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "ingest_key.reveal",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "ingest_key.rotate",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "registration_token.create",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "registration_token.read",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "view"
                            },
                            {
                              "id": "registration_token.reveal",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "registration_token.revoke",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "archive.config.read",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "view"
                            },
                            {
                              "id": "archive.config.write",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "manage"
                            },
                            {
                              "id": "event.query",
                              "level": "org",
                              "category": "event_data",
                              "access_kind": "view"
                            },
                            {
                              "id": "device.read",
                              "level": "org",
                              "category": "event_data",
                              "access_kind": "view"
                            },
                            {
                              "id": "event.read",
                              "level": "org",
                              "category": "raw_logs",
                              "access_kind": "view"
                            },
                            {
                              "id": "analytics.query",
                              "level": "org",
                              "category": "raw_logs",
                              "access_kind": "view"
                            },
                            {
                              "id": "ingestion.read",
                              "level": "org",
                              "category": "billing",
                              "access_kind": "view"
                            },
                            {
                              "id": "finance.admin",
                              "level": "workspace",
                              "category": "billing",
                              "access_kind": "manage"
                            },
                            {
                              "id": "user_token.create_own",
                              "level": "self",
                              "category": null,
                              "access_kind": "manage"
                            },
                            {
                              "id": "user_token.manage_own",
                              "level": "self",
                              "category": null,
                              "access_kind": "manage"
                            },
                            {
                              "id": "user_token.view_all",
                              "level": "org",
                              "category": "people",
                              "access_kind": "view"
                            },
                            {
                              "id": "user_token.manage_any",
                              "level": "org",
                              "category": "people",
                              "access_kind": "manage"
                            },
                            {
                              "id": "workspace_token.create",
                              "level": "org",
                              "category": "people",
                              "access_kind": "manage"
                            },
                            {
                              "id": "workspace_token.view",
                              "level": "org",
                              "category": "people",
                              "access_kind": "view"
                            },
                            {
                              "id": "workspace_token.manage",
                              "level": "org",
                              "category": "people",
                              "access_kind": "manage"
                            },
                            {
                              "id": "app_registration.create",
                              "level": "workspace",
                              "category": "people",
                              "access_kind": "manage"
                            },
                            {
                              "id": "app_registration.view",
                              "level": "workspace",
                              "category": "people",
                              "access_kind": "view"
                            },
                            {
                              "id": "app_registration.manage",
                              "level": "workspace",
                              "category": "people",
                              "access_kind": "manage"
                            }
                          ]
                        },
                        {
                          "id": "organization_admin",
                          "kind": "standard",
                          "description": "Delegated administrator of its organizations, with no workspace rights",
                          "recommended_scope": "selected",
                          "sort_order": 20,
                          "privileges": [
                            {
                              "id": "workspace.read",
                              "level": "self",
                              "category": null,
                              "access_kind": "view"
                            },
                            {
                              "id": "member.read",
                              "level": "org",
                              "category": "people",
                              "access_kind": "view"
                            },
                            {
                              "id": "member.manage",
                              "level": "org",
                              "category": "people",
                              "access_kind": "manage"
                            },
                            {
                              "id": "group.read",
                              "level": "org",
                              "category": "people",
                              "access_kind": "view"
                            },
                            {
                              "id": "group.write",
                              "level": "org",
                              "category": "people",
                              "access_kind": "manage"
                            },
                            {
                              "id": "grant.write",
                              "level": "org",
                              "category": "people",
                              "access_kind": "manage"
                            },
                            {
                              "id": "auditlog.query",
                              "level": "org",
                              "category": "activity_log",
                              "access_kind": "view"
                            },
                            {
                              "id": "organization.read",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "view"
                            },
                            {
                              "id": "organization.create",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "manage"
                            },
                            {
                              "id": "organization.write",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "manage"
                            },
                            {
                              "id": "organization.move",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "manage"
                            },
                            {
                              "id": "organization.delete",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "manage"
                            },
                            {
                              "id": "agent.read",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "view"
                            },
                            {
                              "id": "agent.write",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "agent.delete",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "agent_policy.write",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "agent_policy.assign",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "agent_policy.rule_write",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "agent_tag.attach",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "ingest_key.create",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "ingest_key.reveal",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "ingest_key.rotate",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "registration_token.create",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "registration_token.read",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "view"
                            },
                            {
                              "id": "registration_token.reveal",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "registration_token.revoke",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "archive.config.read",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "view"
                            },
                            {
                              "id": "archive.config.write",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "manage"
                            },
                            {
                              "id": "event.query",
                              "level": "org",
                              "category": "event_data",
                              "access_kind": "view"
                            },
                            {
                              "id": "device.read",
                              "level": "org",
                              "category": "event_data",
                              "access_kind": "view"
                            },
                            {
                              "id": "event.read",
                              "level": "org",
                              "category": "raw_logs",
                              "access_kind": "view"
                            },
                            {
                              "id": "analytics.query",
                              "level": "org",
                              "category": "raw_logs",
                              "access_kind": "view"
                            },
                            {
                              "id": "ingestion.read",
                              "level": "org",
                              "category": "billing",
                              "access_kind": "view"
                            },
                            {
                              "id": "user_token.create_own",
                              "level": "self",
                              "category": null,
                              "access_kind": "manage"
                            },
                            {
                              "id": "user_token.manage_own",
                              "level": "self",
                              "category": null,
                              "access_kind": "manage"
                            },
                            {
                              "id": "user_token.view_all",
                              "level": "org",
                              "category": "people",
                              "access_kind": "view"
                            },
                            {
                              "id": "user_token.manage_any",
                              "level": "org",
                              "category": "people",
                              "access_kind": "manage"
                            },
                            {
                              "id": "workspace_token.create",
                              "level": "org",
                              "category": "people",
                              "access_kind": "manage"
                            },
                            {
                              "id": "workspace_token.view",
                              "level": "org",
                              "category": "people",
                              "access_kind": "view"
                            },
                            {
                              "id": "workspace_token.manage",
                              "level": "org",
                              "category": "people",
                              "access_kind": "manage"
                            }
                          ]
                        },
                        {
                          "id": "engineer",
                          "kind": "standard",
                          "description": "Engineer who can fully manage organizations, deploy agents, and query event data",
                          "recommended_scope": null,
                          "sort_order": 100,
                          "privileges": [
                            {
                              "id": "workspace.read",
                              "level": "self",
                              "category": null,
                              "access_kind": "view"
                            },
                            {
                              "id": "organization.read",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "view"
                            },
                            {
                              "id": "organization.create",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "manage"
                            },
                            {
                              "id": "organization.write",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "manage"
                            },
                            {
                              "id": "organization.delete",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "manage"
                            },
                            {
                              "id": "agent.read",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "view"
                            },
                            {
                              "id": "agent.write",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "agent.delete",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "ingest_key.create",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "ingest_key.reveal",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "ingest_key.rotate",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "registration_token.create",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "registration_token.read",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "view"
                            },
                            {
                              "id": "registration_token.reveal",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "registration_token.revoke",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "archive.config.read",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "view"
                            },
                            {
                              "id": "archive.config.write",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "manage"
                            },
                            {
                              "id": "event.query",
                              "level": "org",
                              "category": "event_data",
                              "access_kind": "view"
                            },
                            {
                              "id": "device.read",
                              "level": "org",
                              "category": "event_data",
                              "access_kind": "view"
                            },
                            {
                              "id": "event.read",
                              "level": "org",
                              "category": "raw_logs",
                              "access_kind": "view"
                            },
                            {
                              "id": "analytics.query",
                              "level": "org",
                              "category": "raw_logs",
                              "access_kind": "view"
                            },
                            {
                              "id": "ingestion.read",
                              "level": "org",
                              "category": "billing",
                              "access_kind": "view"
                            },
                            {
                              "id": "user_token.create_own",
                              "level": "self",
                              "category": null,
                              "access_kind": "manage"
                            },
                            {
                              "id": "user_token.manage_own",
                              "level": "self",
                              "category": null,
                              "access_kind": "manage"
                            }
                          ]
                        },
                        {
                          "id": "analyst",
                          "kind": "standard",
                          "description": "Analyst who can only view and query data but not change anything",
                          "recommended_scope": null,
                          "sort_order": 110,
                          "privileges": [
                            {
                              "id": "workspace.read",
                              "level": "self",
                              "category": null,
                              "access_kind": "view"
                            },
                            {
                              "id": "organization.read",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "view"
                            },
                            {
                              "id": "agent.read",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "view"
                            },
                            {
                              "id": "archive.config.read",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "view"
                            },
                            {
                              "id": "event.query",
                              "level": "org",
                              "category": "event_data",
                              "access_kind": "view"
                            },
                            {
                              "id": "device.read",
                              "level": "org",
                              "category": "event_data",
                              "access_kind": "view"
                            },
                            {
                              "id": "event.read",
                              "level": "org",
                              "category": "raw_logs",
                              "access_kind": "view"
                            },
                            {
                              "id": "analytics.query",
                              "level": "org",
                              "category": "raw_logs",
                              "access_kind": "view"
                            },
                            {
                              "id": "ingestion.read",
                              "level": "org",
                              "category": "billing",
                              "access_kind": "view"
                            },
                            {
                              "id": "user_token.create_own",
                              "level": "self",
                              "category": null,
                              "access_kind": "manage"
                            },
                            {
                              "id": "user_token.manage_own",
                              "level": "self",
                              "category": null,
                              "access_kind": "manage"
                            }
                          ]
                        },
                        {
                          "id": "analyst_no_raw_logs",
                          "kind": "standard",
                          "description": "Analyst who can query counts, patterns and device health but not raw logs",
                          "recommended_scope": null,
                          "sort_order": 120,
                          "privileges": [
                            {
                              "id": "workspace.read",
                              "level": "self",
                              "category": null,
                              "access_kind": "view"
                            },
                            {
                              "id": "organization.read",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "view"
                            },
                            {
                              "id": "agent.read",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "view"
                            },
                            {
                              "id": "archive.config.read",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "view"
                            },
                            {
                              "id": "event.query",
                              "level": "org",
                              "category": "event_data",
                              "access_kind": "view"
                            },
                            {
                              "id": "device.read",
                              "level": "org",
                              "category": "event_data",
                              "access_kind": "view"
                            },
                            {
                              "id": "ingestion.read",
                              "level": "org",
                              "category": "billing",
                              "access_kind": "view"
                            },
                            {
                              "id": "user_token.create_own",
                              "level": "self",
                              "category": null,
                              "access_kind": "manage"
                            },
                            {
                              "id": "user_token.manage_own",
                              "level": "self",
                              "category": null,
                              "access_kind": "manage"
                            }
                          ]
                        },
                        {
                          "id": "deployment_manager",
                          "kind": "standard",
                          "description": "Deploys and manages organizations, agents, agent policy and enrollment, with no data access",
                          "recommended_scope": null,
                          "sort_order": 130,
                          "privileges": [
                            {
                              "id": "workspace.read",
                              "level": "self",
                              "category": null,
                              "access_kind": "view"
                            },
                            {
                              "id": "organization.read",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "view"
                            },
                            {
                              "id": "organization.create",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "manage"
                            },
                            {
                              "id": "organization.write",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "manage"
                            },
                            {
                              "id": "organization.delete",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "manage"
                            },
                            {
                              "id": "agent.read",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "view"
                            },
                            {
                              "id": "agent.write",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "agent.delete",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "agent_policy.write",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "agent_policy.assign",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "agent_policy.rule_write",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "agent_tag.attach",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "ingest_key.create",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "ingest_key.reveal",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "ingest_key.rotate",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "registration_token.create",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "registration_token.read",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "view"
                            },
                            {
                              "id": "registration_token.reveal",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "registration_token.revoke",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "manage"
                            },
                            {
                              "id": "user_token.create_own",
                              "level": "self",
                              "category": null,
                              "access_kind": "manage"
                            },
                            {
                              "id": "user_token.manage_own",
                              "level": "self",
                              "category": null,
                              "access_kind": "manage"
                            }
                          ]
                        },
                        {
                          "id": "auditor",
                          "kind": "standard",
                          "description": "Reads access and configuration, with no data access",
                          "recommended_scope": "all",
                          "sort_order": 140,
                          "privileges": [
                            {
                              "id": "workspace.read",
                              "level": "self",
                              "category": null,
                              "access_kind": "view"
                            },
                            {
                              "id": "member.read",
                              "level": "org",
                              "category": "people",
                              "access_kind": "view"
                            },
                            {
                              "id": "group.read",
                              "level": "org",
                              "category": "people",
                              "access_kind": "view"
                            },
                            {
                              "id": "auditlog.query",
                              "level": "org",
                              "category": "activity_log",
                              "access_kind": "view"
                            },
                            {
                              "id": "organization.read",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "view"
                            },
                            {
                              "id": "agent.read",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "view"
                            },
                            {
                              "id": "registration_token.read",
                              "level": "org",
                              "category": "agents",
                              "access_kind": "view"
                            },
                            {
                              "id": "archive.config.read",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "view"
                            },
                            {
                              "id": "ingestion.read",
                              "level": "org",
                              "category": "billing",
                              "access_kind": "view"
                            },
                            {
                              "id": "user_token.create_own",
                              "level": "self",
                              "category": null,
                              "access_kind": "manage"
                            },
                            {
                              "id": "user_token.manage_own",
                              "level": "self",
                              "category": null,
                              "access_kind": "manage"
                            },
                            {
                              "id": "user_token.view_all",
                              "level": "org",
                              "category": "people",
                              "access_kind": "view"
                            },
                            {
                              "id": "workspace_token.view",
                              "level": "org",
                              "category": "people",
                              "access_kind": "view"
                            },
                            {
                              "id": "app_registration.view",
                              "level": "workspace",
                              "category": "people",
                              "access_kind": "view"
                            }
                          ]
                        },
                        {
                          "id": "finance_admin",
                          "kind": "standard",
                          "description": "Fully manage all financial data and functions, with read access to organizations and no access to event data",
                          "recommended_scope": "all",
                          "sort_order": 400,
                          "privileges": [
                            {
                              "id": "workspace.read",
                              "level": "self",
                              "category": null,
                              "access_kind": "view"
                            },
                            {
                              "id": "organization.read",
                              "level": "org",
                              "category": "organizations",
                              "access_kind": "view"
                            },
                            {
                              "id": "ingestion.read",
                              "level": "org",
                              "category": "billing",
                              "access_kind": "view"
                            },
                            {
                              "id": "finance.admin",
                              "level": "workspace",
                              "category": "billing",
                              "access_kind": "manage"
                            },
                            {
                              "id": "user_token.create_own",
                              "level": "self",
                              "category": null,
                              "access_kind": "manage"
                            },
                            {
                              "id": "user_token.manage_own",
                              "level": "self",
                              "category": null,
                              "access_kind": "manage"
                            }
                          ]
                        }
                      ]
                    }
                  },
                  "without-privileges": {
                    "summary": "List the roles a grant can give, without their privileges",
                    "value": {
                      "message": "roles retrieved",
                      "roles": [
                        {
                          "id": "admin",
                          "kind": "standard",
                          "description": "Administrator with rights to everything, including managing users in the workspace and their roles",
                          "recommended_scope": "all",
                          "sort_order": 10
                        },
                        {
                          "id": "organization_admin",
                          "kind": "standard",
                          "description": "Delegated administrator of its organizations, with no workspace rights",
                          "recommended_scope": "selected",
                          "sort_order": 20
                        },
                        {
                          "id": "engineer",
                          "kind": "standard",
                          "description": "Engineer who can fully manage organizations, deploy agents, and query event data",
                          "recommended_scope": null,
                          "sort_order": 100
                        },
                        {
                          "id": "analyst",
                          "kind": "standard",
                          "description": "Analyst who can only view and query data but not change anything",
                          "recommended_scope": null,
                          "sort_order": 110
                        },
                        {
                          "id": "analyst_no_raw_logs",
                          "kind": "standard",
                          "description": "Analyst who can query counts, patterns and device health but not raw logs",
                          "recommended_scope": null,
                          "sort_order": 120
                        },
                        {
                          "id": "deployment_manager",
                          "kind": "standard",
                          "description": "Deploys and manages organizations, agents, agent policy and enrollment, with no data access",
                          "recommended_scope": null,
                          "sort_order": 130
                        },
                        {
                          "id": "auditor",
                          "kind": "standard",
                          "description": "Reads access and configuration, with no data access",
                          "recommended_scope": "all",
                          "sort_order": 140
                        },
                        {
                          "id": "finance_admin",
                          "kind": "standard",
                          "description": "Fully manage all financial data and functions, with read access to organizations and no access to event data",
                          "recommended_scope": "all",
                          "sort_order": 400
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`APP_API_ERR_BAD_PARAMETERS`: A query parameter it does not take, one given twice, or `fields` naming a field it does not have.\n`APP_API_ERR_BAD_PARAMETERS`: `workspace_id` is not a UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "`APP_API_ERR_UNAUTHORIZED`: The token is missing, not valid, expired or revoked, or its workspace is deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "`APP_API_ERR_NO_PRIVILEGE`: You do not hold `workspace.read`. The same refusal comes when the path names a workspace other than the token's own.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "`APP_API_ERR_TOO_MANY_REQUESTS`: The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`).",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again. With `cause` set to `invalid_token_attempts`, waiting alone does not help.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "`APP_API_ERR_TECHNICAL_ISSUE`: The call failed on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "`APP_API_ERR_MAINTENANCE`: SparkLogs is in scheduled maintenance.",
            "headers": {
              "Retry-After": {
                "description": "The whole seconds to wait before sending the call again.",
                "required": true,
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Send the credential in the `Authorization` header of every call: `Authorization: Bearer <token>`."
      }
    },
    "schemas": {
      "Access": {
        "type": "object",
        "description": "A field not selected with `fields` is absent. A selected field with no value is null.",
        "properties": {
          "privileges": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AccessPrivilege"
            },
            "description": "Every privilege the caller holds here, with where it holds it."
          },
          "credential": {
            "$ref": "#/components/schemas/AccessCredential",
            "description": "The credential the caller presented."
          }
        }
      },
      "AccessCredential": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "x-known-values": [
              "session",
              "user_key",
              "oauth",
              "workspace_key"
            ],
            "description": "What kind of credential it is."
          },
          "credential_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "The API token's id, the `credential_id` audit events name; null for a session."
          },
          "scope_restriction": {
            "type": [
              "string",
              "null"
            ],
            "x-known-values": [
              "none",
              "listed"
            ],
            "description": "Whether the API token is held to a list of scopes; null for a session."
          },
          "scopes": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "The scopes the API token carries: every scope when `scope_restriction` is none; null for a session."
          }
        },
        "required": [
          "kind",
          "credential_id",
          "scope_restriction",
          "scopes"
        ]
      },
      "AccessPrivilege": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The privilege's id."
          },
          "level": {
            "type": "string",
            "x-known-values": [
              "org",
              "workspace",
              "self"
            ],
            "description": "Where the privilege takes effect: each privilege has one level, the same for every caller, as the role list shows it."
          },
          "scope": {
            "description": "For an org privilege, the organizations it reaches, organizations not token scopes: all, or selected with the topmost organizations it reaches that you can see, each with every organization below it. Null for a workspace or self privilege.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/Scope"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "level",
          "scope"
        ]
      },
      "Agent": {
        "type": "object",
        "description": "A field not selected with `fields` is absent. A selected field with no value is null.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The agent's id."
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid",
            "description": "The workspace the agent belongs to."
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "The agent's name. It starts as the host name the agent registered with, as the machine spells it, and follows the host name until someone sets a different name: a check-in reporting a new host name renames the agent, which waits while two machines share the agent's identity. To make it follow again, set the name to the current `reported_hostname`, in any case. To label an agent and keep its name following the host name, use `description`."
          },
          "organization_id": {
            "type": "string",
            "format": "uuid",
            "description": "The organization the agent belongs to."
          },
          "path": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The organization ids from the top-level organization down to the agent's own, then the agent's id."
          },
          "reported_state": {
            "type": [
              "string",
              "null"
            ],
            "description": "The last service state the agent reported, such as running or stopped; unregistered until it first checks in. It is what the agent last said, not whether it is in contact now: a machine that lost power still shows running. `agent_status` says whether it is in contact. More values may be added."
          },
          "agent_status": {
            "type": "string",
            "x-known-values": [
              "online",
              "offline",
              "never_seen",
              "stopped",
              "system_shutdown",
              "uninstalled",
              "upgrading_overdue",
              "deleted"
            ],
            "description": "Whether the agent is in contact, worked out from what it last announced and when anything last arrived from it: on a list at the page's `as_of`, the same instant for every page of one walk, and on a read of one agent when the response is written. It does not change `updated_at`. The same value the SparkLogs MCP server sends. It says nothing about collection: see `collection_status`. These are the values it takes today."
          },
          "reported_state_changed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When `reported_state` last changed."
          },
          "collection_status": {
            "type": [
              "string",
              "null"
            ],
            "description": "SparkLogs' rollup of the agent's collection health across its feeds, worked out from what the agent last reported: healthy, behind, onboarding, degraded or unknown, and more values may be added. Null until first worked out; null and unknown never mean healthy."
          },
          "stuck_reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why the agent is checking in but not collecting; null while it collects."
          },
          "last_data_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When log data from the agent last arrived, recorded at most once every five minutes. It is legitimately old on a quiet, healthy machine. Null until data first arrives."
          },
          "last_heartbeat_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the agent last checked in, about every five minutes while it runs. Null until it first checks in."
          },
          "host_class": {
            "type": [
              "string",
              "null"
            ],
            "description": "The kind of machine the agent runs on: workstation or server today, and more values may be added."
          },
          "reported_hostname": {
            "type": [
              "string",
              "null"
            ],
            "description": "The host name the agent reported, in lower case."
          },
          "rmm_device_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The id your RMM uses for the agent's machine, as the installer was given it or as set later; null when none is recorded. Not unique, and it decides nothing about where the agent belongs or who may act on it."
          },
          "psa_device_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The id your PSA uses for the agent's machine, as the installer was given it or as set later; null when none is recorded. Not unique, and it decides nothing about where the agent belongs or who may act on it."
          },
          "agent_version": {
            "type": [
              "string",
              "null"
            ],
            "description": "The agent's version."
          },
          "os_family": {
            "type": [
              "string",
              "null"
            ],
            "description": "The operating system family the agent reported."
          },
          "os_version": {
            "type": [
              "string",
              "null"
            ],
            "description": "The operating system version the agent reported."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the agent was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the agent's record last changed. Every check-in changes it, and so does arriving log data, so it says little about when anything else about the agent changed."
          },
          "deleted_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the agent was deleted; null while it is live."
          },
          "organization_deleted_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the agent's organization was deleted; null while the organization is live."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "The agent's description."
          },
          "collection_detail": {
            "type": [
              "object",
              "null"
            ],
            "description": "The detail behind `collection_status`, as SparkLogs worked it out from the agent's last report. Its contents are not part of the API contract and may change."
          },
          "collection_feeds": {
            "type": [
              "object",
              "null"
            ],
            "description": "How many of the agent's active feeds report each health, from the same report as `collection_status`. Keys: current, behind, stuck, blocked, onboarding, onboarding_stuck, unknown, and unrecognized for any other value. A health no feed reports is left out. Null when the agent has reported no feeds."
          },
          "update_status": {
            "type": [
              "string",
              "null"
            ],
            "description": "Where the agent's automatic update stands: `idle`, `disabled`, `in_progress`, `reboot_pending` or `failure`; null for an agent that has not reported."
          },
          "update_failure_reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why the agent's last update failed, when it did."
          },
          "install_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The id of the machine the agent is installed on, which stays the same when the agent registers again."
          },
          "synthetic_install_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The agent's `install_id` when SparkLogs assigned it, because too many machines reported the same machine identity; null when the agent uses its machine's own id."
          },
          "rollout_seed": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The agent's place, from 0 to 999999, in a staged update rollout."
          },
          "arch": {
            "type": [
              "string",
              "null"
            ],
            "description": "The processor architecture the agent reported."
          },
          "host_roles": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "The roles the agent reported for its machine; more values may be added."
          },
          "registration_token_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "The registration token the agent registered with."
          },
          "cloned_from_agent_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "The agent this one replaced when its machine was found to be a copy of another; null otherwise."
          },
          "feed_pack_version": {
            "type": [
              "string",
              "null"
            ],
            "description": "The version of the collection definitions the agent last applied."
          },
          "last_meta_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When SparkLogs last stored the agent's operating system and host details, which it refreshes at most every 15 minutes."
          },
          "deletion": {
            "description": "What deleting the agent recorded: whether its machine heard the delete, and when the install comes off. Null while the agent is live.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/AgentDeletion"
              },
              {
                "type": "null"
              }
            ]
          },
          "custom_fields": {
            "type": [
              "object",
              "null"
            ],
            "description": "Custom fields recorded on the agent, as an object of string, number and boolean values. Not for secrets: anyone who may read the agent may read them."
          },
          "host_metadata": {
            "type": [
              "object",
              "null"
            ],
            "description": "The machine details the agent last reported, as an object. Its contents are not part of the API contract and may change."
          },
          "agent_data": {
            "type": [
              "object",
              "null"
            ],
            "description": "What the agent reported about its collection and updates, as an object. Large: it can hold tens of kilobytes per agent. Its contents are not part of the API contract and may change."
          }
        }
      },
      "AgentDeletion": {
        "type": "object",
        "properties": {
          "dormant_since": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the machine reported it heard the delete; null until it does."
          },
          "uninstall_after": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the install comes off; null when it stays or none is recorded."
          },
          "uninstall_never": {
            "type": "boolean",
            "description": "Whether the install stays."
          },
          "uninstall_purge": {
            "type": "boolean",
            "description": "Whether local state goes with it."
          }
        },
        "required": [
          "dormant_since",
          "uninstall_after",
          "uninstall_never",
          "uninstall_purge"
        ]
      },
      "AgentInstaller": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "x-known-values": [
              "exe",
              "msi"
            ],
            "description": "Which installer it is."
          },
          "file_name": {
            "type": "string",
            "description": "The file's name, as the command names it."
          },
          "url": {
            "type": "string",
            "description": "Where to download the file."
          },
          "sha256": {
            "type": "string",
            "description": "The file's SHA-256, lowercase hex."
          },
          "size_bytes": {
            "type": "integer",
            "description": "The file's size in bytes."
          },
          "command": {
            "type": "string",
            "description": "A silent install command for cmd.exe, run from the file's folder. Replace each `<NAME>` with its value, writing a double quote inside a value twice. A parameter with no value is written `NAME=\"\"` or removed whole, never as a bare `NAME=`. From PowerShell, pass the same arguments as the `-ArgumentList` array of `Start-Process`, each value inside its own double quotes and never the whole `NAME=value`: https://sparklogs.com/docs/agents/deploy/cli has the script. The machine registers into the organization at or below the token's that records its `RMMCLIENTID` or `PSACLIENTID`, or a new one directly under the token's named `CLIENTNAME`; to register it into the token's own organization, leave out both ids and `CLIENTNAME` and add `USEPARENTORG=1`."
          }
        },
        "required": [
          "kind",
          "file_name",
          "url",
          "sha256",
          "size_bytes",
          "command"
        ]
      },
      "AgentMove": {
        "type": "object",
        "properties": {
          "organization_id": {
            "type": "string",
            "format": "uuid",
            "description": "The organization to move it to. Moving needs `agent.write` at the agent's organization and `ingest_key.create` at this one. Required."
          }
        },
        "required": [
          "organization_id"
        ]
      },
      "AgentRelease": {
        "type": "object",
        "description": "A field not selected with `fields` is absent. A selected field with no value is null.",
        "properties": {
          "ring": {
            "type": "string",
            "x-known-values": [
              "canary",
              "early_access",
              "stable"
            ],
            "description": "The workspace's update ring, whose release this is."
          },
          "target": {
            "type": "string",
            "x-known-values": [
              "windows_x86_64"
            ],
            "description": "The platform the installers are for."
          },
          "version": {
            "type": "string",
            "description": "The agent version."
          },
          "publisher": {
            "type": "string",
            "description": "The signer of both installers' Authenticode signature. Check it and the file's sha256 before running an installer."
          },
          "installers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentInstaller"
            },
            "description": "The EXE, then the MSI."
          }
        }
      },
      "AgentStatusCounts": {
        "type": "object",
        "properties": {
          "online": {
            "type": "integer",
            "description": "Checked in or sent data in the last 15 minutes."
          },
          "offline": {
            "type": "integer",
            "description": "Nothing has arrived for longer than that, and the agent did not say it was stopping."
          },
          "never_seen": {
            "type": "integer",
            "description": "Enrolled, and nothing has arrived from it yet."
          },
          "stopped": {
            "type": "integer",
            "description": "The agent said its service was stopped."
          },
          "system_shutdown": {
            "type": "integer",
            "description": "The agent said its machine was shutting down."
          },
          "uninstalled": {
            "type": "integer",
            "description": "The agent said it was being uninstalled."
          },
          "upgrading_overdue": {
            "type": "integer",
            "description": "The agent said it was updating itself and has not come back after 30 minutes."
          }
        },
        "required": [
          "online",
          "offline",
          "never_seen",
          "stopped",
          "system_shutdown",
          "uninstalled",
          "upgrading_overdue"
        ]
      },
      "AgentSummary": {
        "type": "object",
        "description": "A field not selected with `fields` is absent. A selected field with no value is null.",
        "properties": {
          "as_of": {
            "type": "string",
            "format": "date-time",
            "description": "The time every count and cutoff below is worked out against."
          },
          "active_since": {
            "type": "string",
            "format": "date-time",
            "description": "Where the active count starts: the `active_since` you sent, or 14 days before `as_of`."
          },
          "inactive_before": {
            "type": "string",
            "format": "date-time",
            "description": "14 days before `as_of`. An agent is inactive when it was created, last sent data, last checked in and last changed status before this time."
          },
          "enrolled": {
            "type": "integer",
            "description": "How many SparkLogs Agents you can see that are not deleted, in organizations that are not deleted. Every count below is of these."
          },
          "active": {
            "type": "integer",
            "description": "How many of them were created or sent data at or after `active_since`."
          },
          "inactive": {
            "type": "integer",
            "description": "How many of them are inactive: nothing about them moved since `inactive_before`."
          },
          "by_agent_status": {
            "$ref": "#/components/schemas/AgentStatusCounts",
            "description": "How many of them read each `agent_status` at `as_of`, as a list of agents shows it."
          },
          "by_collection_status": {
            "$ref": "#/components/schemas/CollectionStatusCounts",
            "description": "How many of them report each `collection_status`."
          }
        }
      },
      "AgentUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 128,
            "description": "The new name, cleaned as every name is. The name follows the machine's host name until a different name is set here; setting it to the current `reported_hostname`, in any case, makes it follow again. To label the agent and keep its name following, set `description` instead. `null` or an empty string returns 400."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 2048,
            "description": "The new description. `null` or an empty string clears it."
          },
          "rmm_device_id": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 256,
            "description": "The id your RMM uses for the agent's machine, cleaned as every name is. A later registration of the machine that names no id keeps it. `null` or an empty string clears it."
          },
          "psa_device_id": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 256,
            "description": "The id your PSA uses for the agent's machine, cleaned as every name is. A later registration of the machine that names no id keeps it. `null` or an empty string clears it."
          },
          "custom_fields": {
            "type": [
              "object",
              "null"
            ],
            "description": "Changes to the custom fields, merged into the stored ones: a key left out keeps its value, null removes it, and a string, a boolean, or a number of at most 32 characters in plain decimal digits with no exponent sets it. A number is kept by its value, so 1.50 reads back as 1.5. At most 50 keys, each 1 to 64 letters, digits, `_`, `-` and `.`, and 8 KiB as JSON. Write a time as RFC 3339 in UTC. Not for secrets."
          }
        }
      },
      "AuditEvent": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The event's id."
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the event first happened."
          },
          "last_occurred_at": {
            "type": "string",
            "format": "date-time",
            "description": "When it last happened: the same refusal repeated within a minute folds into one event, which keeps the first call's details, an MCP tool call's `mcp_operation_id` included."
          },
          "occurrences": {
            "type": "integer",
            "description": "How many times it happened."
          },
          "actor_kind": {
            "type": "string",
            "description": "What acted: user for a person, `workspace_key` for a workspace token, and others."
          },
          "actor_id": {
            "type": "string",
            "description": "The id of who acted."
          },
          "actor_desc": {
            "type": [
              "string",
              "null"
            ],
            "description": "Who acted, for a person to read. In a signed-in session, the member's email address. With an API token, the token's kind and the first 8 characters of its id (an OAuth token's app registration id), after the email address of the member it acts as: 'name@example.com (API token 1a2b3c4d)', 'name@example.com (connected app 9f8e7d6c)', 'workspace token 1a2b3c4d'. Null on older events and for someone outside the workspace."
          },
          "credential_kind": {
            "type": "string",
            "description": "The credential used: session, `user_key`, oauth or `workspace_key`."
          },
          "credential_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "The API token used; null for a session."
          },
          "action": {
            "type": "string",
            "description": "What was done, such as `organization.create`."
          },
          "privileges": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The privileges the route asks for, not what the actor holds."
          },
          "target_kind": {
            "type": [
              "string",
              "null"
            ],
            "description": "The kind of thing acted on."
          },
          "target_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The id of the thing acted on; null when you are not shown it."
          },
          "target_desc": {
            "type": [
              "string",
              "null"
            ],
            "description": "The thing acted on, for a person to read; null when you are not shown it."
          },
          "target_hidden": {
            "type": "boolean",
            "description": "Sent as true when the target's id or name is withheld from you."
          },
          "org_ids": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The organizations the event touched that you can see; null when the event names no organization."
          },
          "all_orgs": {
            "type": "boolean",
            "description": "Whether the event covered every organization; `org_ids` then lists only those its details name."
          },
          "other_orgs": {
            "type": "boolean",
            "description": "Sent as true when the event touched an organization you cannot see, left out without an id or a count."
          },
          "details_withheld": {
            "type": "boolean",
            "description": "Sent as true when the event has details you are not shown."
          },
          "outcome": {
            "type": "string",
            "description": "How the call ended, such as allowed, denied or failed."
          },
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why a call was refused or failed: on a refusal, `token_scope` when only the API token's scopes refused it, else the privileges the call needs; on a failure, the error code."
          },
          "details": {
            "type": [
              "object",
              "null"
            ],
            "description": "What the event recorded about the call, as an object whose keys depend on the action. A call made with an API token adds `credential_short_id`, as in `actor_desc`, and `credential_label`, the token's label or the OAuth app's name as it was when the event was written, or {\"hidden\": true} when the token covers an organization you cannot see. Null when the event recorded no details, or when you are not shown them (`details_withheld`)."
          },
          "details_v": {
            "type": "integer",
            "description": "Sent as 1 when details are shown field by field as the action declares them; left out on an older event, shown whole or withheld whole."
          },
          "ip": {
            "type": [
              "string",
              "null"
            ],
            "description": "The address the call came from. For a call made through the SparkLogs MCP server, the address of the MCP client."
          },
          "user_agent": {
            "type": [
              "string",
              "null"
            ],
            "description": "The user agent the call sent. For a call made through the SparkLogs MCP server, the user agent of the MCP client."
          },
          "invocation_method": {
            "type": "string",
            "x-known-values": [
              "direct",
              "mcp"
            ],
            "description": "How the call reached SparkLogs."
          }
        },
        "required": [
          "id",
          "occurred_at",
          "last_occurred_at",
          "occurrences",
          "actor_kind",
          "actor_id",
          "actor_desc",
          "credential_kind",
          "credential_id",
          "action",
          "privileges",
          "target_kind",
          "target_id",
          "target_desc",
          "org_ids",
          "all_orgs",
          "outcome",
          "reason",
          "details",
          "ip",
          "user_agent",
          "invocation_method"
        ]
      },
      "AuditEventPage": {
        "type": "object",
        "properties": {
          "audit_events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AuditEvent"
            },
            "description": "The events, newest first."
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Null on the last page. Otherwise pass it as `cursor`, with the same filters, for the next page of older events."
          },
          "message": {
            "type": "string",
            "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
          }
        },
        "required": [
          "audit_events",
          "next_cursor",
          "message"
        ]
      },
      "AuditEventRead": {
        "type": "object",
        "properties": {
          "audit_event": {
            "$ref": "#/components/schemas/AuditEvent",
            "description": "The event, its lists whole."
          },
          "message": {
            "type": "string",
            "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
          }
        },
        "required": [
          "audit_event",
          "message"
        ]
      },
      "ClientIDCheck": {
        "type": "object",
        "properties": {
          "rmm_client_id": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 256,
            "description": "The RMM client id to look for, matched once cleaned as every name is, ignoring case. Send this or `psa_client_id`, not both."
          },
          "psa_client_id": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 256,
            "description": "The PSA client id to look for, matched once cleaned as every name is, ignoring case. Send this or `rmm_client_id`, not both."
          },
          "exclude_organization_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "An organization to leave out of the response, such as the one being edited."
          },
          "privilege_organization_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "The organization you are creating under or editing: you need `organization.create` or `organization.write` there. Left out, you need one of them over every organization."
          }
        }
      },
      "ClientIDCheckResult": {
        "type": "object",
        "properties": {
          "live_count": {
            "type": "integer",
            "description": "How many live organizations in the workspace record the id, ones you cannot see included and `exclude_organization_id` left out."
          },
          "deleted_count": {
            "type": "integer",
            "description": "How many deleted organizations in the workspace record the id, ones you cannot see included and `exclude_organization_id` left out."
          },
          "visible_matches": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ClientIDMatch"
            },
            "description": "The organizations recording the id that you can see, deleted ones included."
          },
          "message": {
            "type": "string",
            "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
          }
        },
        "required": [
          "live_count",
          "deleted_count",
          "visible_matches",
          "message"
        ]
      },
      "ClientIDMatch": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The organization's id."
          },
          "name": {
            "type": "string",
            "description": "The organization's name."
          },
          "path": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The ids from the top-level organization down to this one, ending with its own id."
          },
          "deleted": {
            "type": "boolean",
            "description": "Whether the organization is deleted: true for a deleted one, false for a live one."
          }
        },
        "required": [
          "id",
          "name",
          "path",
          "deleted"
        ]
      },
      "CollectionStatusCounts": {
        "type": "object",
        "properties": {
          "healthy": {
            "type": "integer",
            "description": "How many report `healthy`."
          },
          "behind": {
            "type": "integer",
            "description": "How many report `behind`."
          },
          "onboarding": {
            "type": "integer",
            "description": "How many report `onboarding`."
          },
          "degraded": {
            "type": "integer",
            "description": "How many report `degraded`."
          },
          "unknown": {
            "type": "integer",
            "description": "How many report `unknown`."
          },
          "none": {
            "type": "integer",
            "description": "No collection status worked out yet: `collection_status` is null."
          }
        },
        "required": [
          "healthy",
          "behind",
          "onboarding",
          "degraded",
          "unknown",
          "none"
        ]
      },
      "Credential": {
        "type": "object",
        "description": "A field not selected with `fields` is absent. A selected field with no value is null.",
        "properties": {
          "kind": {
            "type": "string",
            "x-known-values": [
              "session",
              "user_key",
              "oauth",
              "workspace_key"
            ],
            "description": "What kind of credential it is."
          },
          "credential_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "The API token's id, the `credential_id` audit events name; null for a session."
          },
          "workspace_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "The one workspace the API token belongs to; null for a session."
          },
          "region_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The id of the region that workspace's data lives in; null for a session."
          },
          "scope_restriction": {
            "type": [
              "string",
              "null"
            ],
            "x-known-values": [
              "none",
              "listed"
            ],
            "description": "Whether the API token is held to a list of scopes; null for a session."
          },
          "scopes": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "The scopes the API token carries: every scope when `scope_restriction` is none; null for a session."
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the API token stops working; null when it never expires, and for a session."
          }
        }
      },
      "CredentialRotated": {
        "type": "object",
        "properties": {
          "credential_id": {
            "type": "string",
            "format": "uuid",
            "description": "The API token's id, which rotation does not change."
          },
          "token": {
            "type": "string",
            "description": "The new secret. It is sent only this once and cannot be read again. The old secret is refused in every region `cache_clear_status` says the change reached."
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid",
            "description": "The workspace the API token belongs to."
          },
          "user_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The person a personal token acts as; null for a workspace token."
          },
          "label": {
            "type": [
              "string",
              "null"
            ],
            "description": "The API token's label."
          },
          "scope_restriction": {
            "type": "string",
            "x-known-values": [
              "none",
              "listed"
            ],
            "description": "Whether the API token is held to a list of scopes."
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The scopes the API token carries: every scope when `scope_restriction` is none."
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the API token stops working, which rotation does not change; null when it does not expire."
          },
          "cache_clear_by_region": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": {
              "type": "string"
            },
            "description": "For each region whose cache may still hold the old secret, whether that cache dropped it: ok, failed or disabled. Null when there was nothing to drop."
          },
          "cache_clear_status": {
            "type": "string",
            "x-known-values": [
              "ok",
              "failed",
              "disabled"
            ],
            "description": "Whether every region refuses the old secret."
          },
          "cache_clear_message": {
            "type": [
              "string",
              "null"
            ],
            "description": "Sent with a `cache_clear_status` other than ok: what it means, for a person to read."
          },
          "message": {
            "type": "string",
            "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
          }
        },
        "required": [
          "credential_id",
          "token",
          "workspace_id",
          "user_id",
          "label",
          "scope_restriction",
          "scopes",
          "expires_at",
          "cache_clear_by_region",
          "cache_clear_status",
          "message"
        ]
      },
      "Grant": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The grant's id; left out on a grant an invitation will become."
          },
          "role_id": {
            "type": "string",
            "description": "The role the grant gives."
          },
          "scope": {
            "$ref": "#/components/schemas/Scope",
            "description": "Which organizations the grant covers. With all, every organization and the workspace: the role's workspace-level privileges apply too. With selected, the organizations in `org_ids` and everything below them: the role's workspace-level privileges do not apply. With workspace, the workspace alone: only the role's workspace-level privileges apply. Your own grants show whole. Changing or removing a grant with `inherited` or `other_orgs` needs access over organizations you cannot see; without it the call returns 403 `APP_API_ERR_BEYOND_OWN_AUTHORITY`."
          }
        },
        "required": [
          "role_id",
          "scope"
        ]
      },
      "GrantBatch": {
        "type": "object",
        "properties": {
          "grantee": {
            "$ref": "#/components/schemas/Grantee",
            "description": "Whose grants change. Required."
          },
          "remove": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The ids of the grants to remove."
          },
          "update": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/GrantUpdate"
            },
            "description": "The grants to change, each by id."
          },
          "add": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/GrantRequest"
            },
            "description": "The grants to add."
          }
        },
        "required": [
          "grantee"
        ]
      },
      "GrantCreate": {
        "type": "object",
        "properties": {
          "grantee": {
            "$ref": "#/components/schemas/Grantee",
            "description": "Who the grant is given to. Required."
          },
          "role_id": {
            "type": "string",
            "description": "The role the grant gives. Required."
          },
          "scope": {
            "$ref": "#/components/schemas/Scope",
            "description": "Which organizations the grant covers. With all, every organization and the workspace: the role's workspace-level privileges apply too. With selected, the organizations in `org_ids` and everything below them: the role's workspace-level privileges do not apply. With workspace, the workspace alone: only the role's workspace-level privileges apply. Required."
          }
        },
        "required": [
          "grantee",
          "role_id",
          "scope"
        ]
      },
      "GrantRequest": {
        "type": "object",
        "properties": {
          "role_id": {
            "type": "string",
            "description": "The role the grant gives. Required."
          },
          "scope": {
            "$ref": "#/components/schemas/Scope",
            "description": "Which organizations the grant covers. With all, every organization and the workspace: the role's workspace-level privileges apply too. With selected, the organizations in `org_ids` and everything below them: the role's workspace-level privileges do not apply. With workspace, the workspace alone: only the role's workspace-level privileges apply. Required."
          }
        },
        "required": [
          "role_id",
          "scope"
        ]
      },
      "GrantUpdate": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The grant to change. Required."
          },
          "role_id": {
            "type": "string",
            "description": "The role it gives from now on. Required."
          },
          "scope": {
            "$ref": "#/components/schemas/Scope",
            "description": "Which organizations it covers from now on, as a grant's `scope` says. Required."
          }
        },
        "required": [
          "id",
          "role_id",
          "scope"
        ]
      },
      "Grantee": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "user",
              "group",
              "workspace_key"
            ],
            "description": "What kind of grantee `id` names."
          },
          "id": {
            "type": "string",
            "description": "The member's user id, the group's id or the workspace token's id."
          }
        }
      },
      "GrantsChanged": {
        "type": "object",
        "properties": {
          "removed": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The ids of the grants removed."
          },
          "updated": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The ids of the grants changed."
          },
          "added": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The ids of the grants added, in the order add named them."
          },
          "cache_clear_status": {
            "type": "string",
            "x-known-values": [
              "ok",
              "failed",
              "disabled"
            ],
            "description": "How far the change got into every region's cache."
          },
          "cache_clear_message": {
            "type": [
              "string",
              "null"
            ],
            "description": "Sent with a `cache_clear_status` other than ok: what it means, for a person to read."
          },
          "message": {
            "type": "string",
            "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
          }
        },
        "required": [
          "removed",
          "updated",
          "added",
          "cache_clear_status",
          "message"
        ]
      },
      "Group": {
        "type": "object",
        "description": "A field not selected with `fields` is absent. A selected field with no value is null.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The group's id."
          },
          "name": {
            "type": "string",
            "description": "The group's name."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the group was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the group last changed."
          },
          "grants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Grant"
            },
            "description": "The group's grants you are shown."
          },
          "other_grants": {
            "type": "boolean",
            "description": "True when the group holds a grant you are not shown."
          },
          "member_count": {
            "type": "integer",
            "description": "How many members are in the group."
          },
          "members": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GroupMember"
            },
            "description": "Everyone in the group, name and email only, as `read-group` shows them: sent only when `fields` names it, then a list, empty for a group with no members."
          }
        }
      },
      "GroupCreate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 128,
            "description": "The group's name. Cleaned, as every name is. Required."
          },
          "grants": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/GrantRequest"
            },
            "description": "The group's grants. A group with none needs `group.write` over every organization."
          },
          "user_ids": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Members to put in the group, each one you are shown."
          }
        },
        "required": [
          "name"
        ]
      },
      "GroupDetail": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The group's id."
          },
          "name": {
            "type": "string",
            "description": "The group's name."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the group was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the group last changed."
          },
          "grants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Grant"
            },
            "description": "The group's grants you are shown."
          },
          "other_grants": {
            "type": "boolean",
            "description": "True when the group holds a grant you are not shown."
          },
          "member_count": {
            "type": "integer",
            "description": "How many members are in the group."
          },
          "members": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GroupMember"
            },
            "description": "Everyone in the group, name and email only, whatever your reach, so the whole membership can be sent back changed."
          }
        },
        "required": [
          "id",
          "name",
          "created_at",
          "updated_at",
          "grants",
          "other_grants",
          "member_count",
          "members"
        ]
      },
      "GroupMember": {
        "type": "object",
        "properties": {
          "user_id": {
            "type": "string",
            "description": "The member's user id."
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "The member's email address."
          },
          "full_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "The member's full name."
          },
          "display_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "The name the app shows for the member."
          }
        },
        "required": [
          "user_id",
          "email",
          "full_name",
          "display_name"
        ]
      },
      "GroupMembers": {
        "type": "object",
        "properties": {
          "user_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Everyone who is in the group from now on; an empty list empties it. Required."
          }
        },
        "required": [
          "user_ids"
        ]
      },
      "GroupRead": {
        "type": "object",
        "properties": {
          "group": {
            "$ref": "#/components/schemas/GroupDetail",
            "description": "The group."
          },
          "message": {
            "type": "string",
            "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
          }
        },
        "required": [
          "group",
          "message"
        ]
      },
      "GroupRef": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The group's id."
          },
          "name": {
            "type": "string",
            "description": "The group's name."
          }
        },
        "required": [
          "id",
          "name"
        ]
      },
      "GroupRename": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 128,
            "description": "The new name. Cleaned, as every name is. Required."
          }
        },
        "required": [
          "name"
        ]
      },
      "IDResult": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The id of the row the call created or changed."
          },
          "cache_clear_status": {
            "type": [
              "string",
              "null"
            ],
            "x-known-values": [
              "ok",
              "failed",
              "disabled"
            ],
            "description": "Sent when the change has to reach every region's cache: how far it got."
          },
          "cache_clear_message": {
            "type": [
              "string",
              "null"
            ],
            "description": "Sent with a `cache_clear_status` other than ok: what it means, for a person to read."
          },
          "message": {
            "type": "string",
            "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
          }
        },
        "required": [
          "id",
          "message"
        ]
      },
      "IngestKey": {
        "type": "object",
        "description": "A field not selected with `fields` is absent. A selected field with no value is null.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The ingest key's id."
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid",
            "description": "The workspace the ingest key belongs to."
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "The ingest key's name, a label that changes only when you change it."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "The ingest key's description."
          },
          "organization_id": {
            "type": "string",
            "format": "uuid",
            "description": "The organization the ingest key sends data for."
          },
          "path": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The organization ids from the top-level organization down to the key's own, then the key's id."
          },
          "data_status": {
            "type": "string",
            "x-known-values": [
              "online",
              "offline",
              "never_seen",
              "deleted"
            ],
            "description": "Whether data is arriving with the key, worked out from when its data last arrived: on a list at the page's `as_of`, the same instant for every page of one walk, and on a read of one key when the response is written. A key has no heartbeat, so a sender that sends nothing for hours reads offline. The SparkLogs MCP server shows the same value as `agent_status` on an ingest key's row."
          },
          "last_data_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When log data sent with the key last arrived, recorded at most once every five minutes. Null until data first arrives."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the ingest key was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the ingest key's record last changed. Arriving data changes it, so it says little about when anything else about the key changed."
          },
          "deleted_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the ingest key was deleted; null while it is live."
          },
          "organization_deleted_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the key's organization was deleted; null while the organization is live."
          },
          "custom_fields": {
            "type": [
              "object",
              "null"
            ],
            "description": "Custom fields recorded on the ingest key, as an object of string, number and boolean values. Not for secrets: anyone who may read the ingest key may read them."
          }
        }
      },
      "IngestKeyCreate": {
        "type": "object",
        "properties": {
          "organization_id": {
            "type": "string",
            "format": "uuid",
            "description": "The organization the ingest key sends data for. Required."
          },
          "name": {
            "type": "string",
            "maxLength": 128,
            "description": "The ingest key's name. Cleaned, as every name is. Required."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 2048,
            "description": "The ingest key's description."
          }
        },
        "required": [
          "organization_id",
          "name"
        ]
      },
      "IngestKeyCreated": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The new ingest key's id."
          },
          "key": {
            "type": "string",
            "description": "The key a sender presents to send log data. Keep it secret; it can be read again later by anyone holding `ingest_key.reveal`."
          },
          "message": {
            "type": "string",
            "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
          }
        },
        "required": [
          "id",
          "key",
          "message"
        ]
      },
      "IngestKeyMove": {
        "type": "object",
        "properties": {
          "organization_id": {
            "type": "string",
            "format": "uuid",
            "description": "The organization to move it to. Moving needs `agent.write` at the key's organization and `ingest_key.create` at this one. Required."
          }
        },
        "required": [
          "organization_id"
        ]
      },
      "IngestKeyRotated": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "The new key a sender presents to send log data."
          },
          "cache_clear_status": {
            "type": "string",
            "x-known-values": [
              "ok",
              "failed",
              "disabled"
            ],
            "description": "Whether every region refuses the old key."
          },
          "cache_clear_message": {
            "type": [
              "string",
              "null"
            ],
            "description": "Sent with a `cache_clear_status` other than ok: what it means, for a person to read."
          },
          "message": {
            "type": "string",
            "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
          }
        },
        "required": [
          "key",
          "cache_clear_status",
          "message"
        ]
      },
      "IngestKeySecret": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "The key a sender presents to send log data."
          },
          "message": {
            "type": "string",
            "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
          }
        },
        "required": [
          "key",
          "message"
        ]
      },
      "IngestKeyUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 128,
            "description": "The new name, a label only. Cleaned, as every name is. `null` or an empty string returns 400."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 2048,
            "description": "The new description. `null` or an empty string clears it."
          },
          "custom_fields": {
            "type": [
              "object",
              "null"
            ],
            "description": "Changes to the custom fields, merged into the stored ones: a key left out keeps its value, null removes it, and a string, a boolean, or a number of at most 32 characters in plain decimal digits with no exponent sets it. A number is kept by its value, so 1.50 reads back as 1.5. At most 50 keys, each 1 to 64 letters, digits, `_`, `-` and `.`, and 8 KiB as JSON. Write a time as RFC 3339 in UTC. Not for secrets."
          }
        }
      },
      "IngestPolicyPatch": {
        "type": "object",
        "properties": {
          "uncurated_max_severity": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "maximum": 24,
            "description": "The highest severity an uncurated event is stored at: a higher one is lowered to it. Clearing it removes the cap. `null` clears it."
          },
          "uncurated_syslog_max_severity": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "maximum": 24,
            "description": "The same cap for uncurated syslog events. `null` clears it."
          }
        }
      },
      "IngestPolicyUpdate": {
        "type": "object",
        "properties": {
          "ingest_policy": {
            "$ref": "#/components/schemas/IngestPolicyPatch",
            "description": "Changes to the ingest policy, merged into the stored one: a key left out keeps its value. Left out, nothing changes. `null` returns 400."
          }
        }
      },
      "IngestPolicyUpdated": {
        "type": "object",
        "properties": {
          "ingest_policy": {
            "type": [
              "object",
              "null"
            ],
            "description": "The stored ingest policy after the change."
          },
          "message": {
            "type": "string",
            "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
          }
        },
        "required": [
          "ingest_policy",
          "message"
        ]
      },
      "Invitation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The invitation's id."
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "The email address invited."
          },
          "grants": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/Grant"
            },
            "description": "The grants the person holds once they accept, those you are shown."
          },
          "other_grants": {
            "type": "boolean",
            "description": "True when the invitation carries a grant you are not shown."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the invitation was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the invitation last changed."
          },
          "last_sent_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the invitation email was last sent; null when it never was."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the invitation stops being valid. Sending it again moves this later."
          },
          "invited_by_user_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The user id of the member who sent the invitation. Null when no sender is recorded, when the sender has left, or when you are not shown them."
          },
          "sender_removed": {
            "type": "boolean",
            "description": "Whether the recorded sender is no longer a member."
          }
        },
        "required": [
          "id",
          "email",
          "grants",
          "other_grants",
          "created_at",
          "updated_at",
          "last_sent_at",
          "expires_at",
          "invited_by_user_id",
          "sender_removed"
        ]
      },
      "InvitationCreate": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "The email address to invite. Required."
          },
          "grants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GrantRequest"
            },
            "description": "The grants the person holds once they accept. An empty list invites with none, which needs `member.manage` over every organization. Required."
          },
          "invitation_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "The invitation to save again, or the id to give a new one: a UUID, which you may choose. Left out, the email's pending invitation is saved again, or a new one is given a new id. A different id for an email with a pending invitation returns 409."
          }
        },
        "required": [
          "email",
          "grants"
        ]
      },
      "InvitationPage": {
        "type": "object",
        "properties": {
          "invitations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Invitation"
            },
            "description": "The pending invitations you are shown, oldest first."
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Null on the last page. Otherwise pass it as `cursor`, with the same filters, for the next page."
          },
          "message": {
            "type": "string",
            "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
          }
        },
        "required": [
          "invitations",
          "next_cursor",
          "message"
        ]
      },
      "JobStatus": {
        "type": "object",
        "properties": {
          "job_type": {
            "type": "string",
            "description": "The kind of job."
          },
          "last_job_id": {
            "type": "string",
            "description": "The id of the job's latest run."
          },
          "summary": {
            "type": [
              "string",
              "null"
            ],
            "description": "A one-line account of the latest run."
          },
          "details": {
            "type": [
              "string",
              "null"
            ],
            "description": "What the latest run did, as text. Its contents are not part of the API contract and may change."
          },
          "healthy": {
            "type": "boolean",
            "description": "Whether the latest run left the job healthy."
          },
          "severity": {
            "type": "integer",
            "description": "How serious the latest run's outcome is, on the log severity scale: 9 ok, 13 warning, 17 error, 21 fatal."
          },
          "status": {
            "type": "string",
            "description": "Where the latest run stands."
          },
          "started_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the latest run started."
          },
          "finished_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the latest run finished."
          },
          "extra_data": {
            "type": [
              "object",
              "null"
            ],
            "description": "More about the latest run, as an object. Its contents are not part of the API contract and may change."
          }
        },
        "required": [
          "job_type",
          "last_job_id",
          "summary",
          "details",
          "healthy",
          "severity",
          "status",
          "started_at",
          "finished_at",
          "extra_data"
        ]
      },
      "Member": {
        "type": "object",
        "properties": {
          "user_id": {
            "type": "string",
            "description": "The member's user id."
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "The member's email address."
          },
          "full_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "The member's full name."
          },
          "display_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "The name the app shows for the member."
          },
          "is_self": {
            "type": "boolean",
            "description": "Whether the member is you."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the member joined the workspace."
          },
          "deleted_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the person's account was deleted; null while it is active."
          },
          "grants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Grant"
            },
            "description": "The member's own grants you are shown: all of yours, and anyone else's inside your reach. Grants held through a group are on the group."
          },
          "other_grants": {
            "type": "boolean",
            "description": "True when the member holds a grant you are not shown."
          },
          "groups": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GroupRef"
            },
            "description": "The groups the member is in that `group.read` shows you; on your own row, every group you are in."
          }
        },
        "required": [
          "user_id",
          "email",
          "full_name",
          "display_name",
          "is_self",
          "created_at",
          "deleted_at",
          "grants",
          "other_grants",
          "groups"
        ]
      },
      "MemberPage": {
        "type": "object",
        "properties": {
          "members": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Member"
            },
            "description": "The members you are shown, deleted accounts included, oldest membership first."
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Null on the last page. Otherwise pass it as `cursor`, with the same filters, for the next page."
          },
          "message": {
            "type": "string",
            "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
          }
        },
        "required": [
          "members",
          "next_cursor",
          "message"
        ]
      },
      "OnboardingPatch": {
        "type": "object",
        "properties": {
          "persona": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "msp_it",
              "game_app",
              "sre_dev",
              null
            ],
            "description": "Who the workspace is for."
          },
          "wizard_status": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "not_started",
              "in_progress",
              "automated_complete",
              "completed",
              "dismissed",
              null
            ],
            "description": "Where the setup wizard stands."
          },
          "wizard_version": {
            "type": "integer",
            "description": "The setup wizard's version. `null` returns 400."
          },
          "wizard_automated_completed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the wizard's automated steps finished. `null` clears it."
          },
          "setup_mode": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "recommended",
              "advanced",
              null
            ],
            "description": "Which setup the wizard follows."
          },
          "manual_tasks": {
            "type": [
              "object",
              "null"
            ],
            "description": "By task id, each an object of `completed_at` and `skipped_at`, a time or null to clear it."
          },
          "dismissed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When onboarding was dismissed. `null` clears it."
          },
          "wizard_state": {
            "type": [
              "object",
              "null"
            ],
            "description": "The wizard's own state, an object."
          },
          "wizard_data": {
            "type": [
              "object",
              "null"
            ],
            "description": "The wizard's own lasting facts, an object."
          }
        }
      },
      "OnboardingUpdate": {
        "type": "object",
        "properties": {
          "onboarding": {
            "$ref": "#/components/schemas/OnboardingPatch",
            "description": "Changes to the onboarding state, merged into the stored one: a key left out keeps its value. Left out, nothing changes. `null` returns 400."
          }
        }
      },
      "OnboardingUpdated": {
        "type": "object",
        "properties": {
          "onboarding": {
            "type": [
              "object",
              "null"
            ],
            "description": "The stored onboarding state after the change."
          },
          "message": {
            "type": "string",
            "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
          }
        },
        "required": [
          "onboarding",
          "message"
        ]
      },
      "Organization": {
        "type": "object",
        "description": "A field not selected with `fields` is absent. A selected field with no value is null.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The organization's id."
          },
          "parent_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "The parent organization's id; null for a top-level organization."
          },
          "path": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The ids from the top-level organization down to this one, ending with its own id."
          },
          "name": {
            "type": "string",
            "description": "The organization's name."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "The organization's description."
          },
          "rmm_client_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The id your RMM uses for this client. Not unique: several organizations may record the same id."
          },
          "psa_client_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The id your PSA uses for this client. Not unique: several organizations may record the same id."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the organization was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the organization last changed. A change above it in the tree, such as a parent's move, does not change it."
          },
          "deleted_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the organization was deleted; null while it is live."
          },
          "custom_fields": {
            "type": [
              "object",
              "null"
            ],
            "description": "Custom fields recorded on the organization, as an object of string, number and boolean values. Not for secrets: anyone who may read the organization may read them."
          }
        }
      },
      "OrganizationCreate": {
        "type": "object",
        "properties": {
          "parent_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "The organization to create it under; leave it out to create a top-level organization."
          },
          "name": {
            "type": "string",
            "maxLength": 128,
            "description": "The organization's name. Cleaned, as every name is. Required."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 2048,
            "description": "The organization's description."
          },
          "rmm_client_id": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 256,
            "description": "The id your RMM uses for this client, cleaned as every name is. Not unique: other organizations may record the same id. Agent installs that pass this id land here."
          },
          "psa_client_id": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 256,
            "description": "The id your PSA uses for this client, cleaned as every name is. Not unique: other organizations may record the same id."
          }
        },
        "required": [
          "name"
        ]
      },
      "OrganizationCreated": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The new organization's id."
          },
          "cache_clear_status": {
            "type": "string",
            "x-known-values": [
              "ok",
              "failed",
              "disabled"
            ],
            "description": "How far the new organization got into every region's cache."
          },
          "cache_clear_message": {
            "type": [
              "string",
              "null"
            ],
            "description": "Sent with a `cache_clear_status` other than ok: what it means, for a person to read."
          },
          "message": {
            "type": "string",
            "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
          }
        },
        "required": [
          "id",
          "cache_clear_status",
          "message"
        ]
      },
      "OrganizationMove": {
        "type": "object",
        "properties": {
          "parent_id": {
            "type": "string",
            "format": "uuid",
            "description": "The organization to move it under. Moving needs `organization.move` at the organization's current parent and at this one. Required."
          }
        },
        "required": [
          "parent_id"
        ]
      },
      "OrganizationUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 128,
            "description": "The new name. Cleaned, as every name is. `null` or an empty string returns 400."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 2048,
            "description": "The new description. `null` or an empty string clears it."
          },
          "rmm_client_id": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 256,
            "description": "The new RMM client id, cleaned as every name is. Agent installs that pass this id land here. `null` or an empty string clears it."
          },
          "psa_client_id": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 256,
            "description": "The new PSA client id, cleaned as every name is. `null` or an empty string clears it."
          },
          "custom_fields": {
            "type": [
              "object",
              "null"
            ],
            "description": "Changes to the custom fields, merged into the stored ones: a key left out keeps its value, null removes it, and a string, a boolean, or a number of at most 32 characters in plain decimal digits with no exponent sets it. A number is kept by its value, so 1.50 reads back as 1.5. At most 50 keys, each 1 to 64 letters, digits, `_`, `-` and `.`, and 8 KiB as JSON. Write a time as RFC 3339 in UTC. Not for secrets."
          }
        }
      },
      "Region": {
        "type": "object",
        "description": "A field not selected with `fields` is absent. A selected field with no value is null.",
        "properties": {
          "id": {
            "type": "string",
            "description": "The region's id."
          },
          "name": {
            "type": "string",
            "description": "The region's name."
          },
          "sort_order": {
            "type": "integer",
            "description": "Where the region sorts in a list of regions."
          },
          "ingest_uri": {
            "type": "string",
            "description": "The address agents send this region's log data to."
          },
          "query_uri": {
            "type": "string",
            "description": "The address this region's data is queried at."
          },
          "bigquery_location": {
            "type": [
              "string",
              "null"
            ],
            "description": "The BigQuery location this region's workspace datasets are created in, such as `US`. list-regions returns it only when named in `fields`; a workspace's region always carries it."
          }
        }
      },
      "RegistrationToken": {
        "type": "object",
        "description": "A field not selected with `fields` is absent. A selected field with no value is null.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The token's id."
          },
          "organization_id": {
            "type": "string",
            "format": "uuid",
            "description": "The organization agents installed with the token register into, or into an organization below it."
          },
          "path": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The organization ids from the top-level organization down to the token's own, then the token's id."
          },
          "label": {
            "type": [
              "string",
              "null"
            ],
            "description": "The token's name; null when it has none."
          },
          "status": {
            "type": "string",
            "x-known-values": [
              "active",
              "revoked",
              "expired"
            ],
            "description": "Whether agents can register with the token, worked out on a list at the page's `as_of`, the same instant for every page of one walk, and on a read of one token when the response is written: revoked once revoked, else expired once `expires_at` has passed, else active. Whether it is deleted is `deleted_at`. Passing `expires_at` does not change `updated_at`."
          },
          "created_by_user_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The member who created the token. Null when you are not shown that member, when the member has left, or when a workspace token created it."
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the token stops working; null when it does not expire."
          },
          "revoked_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the token was revoked; null while it is not."
          },
          "revocation_reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why the token was revoked, as the person revoking it wrote."
          },
          "use_count": {
            "type": "integer",
            "description": "How many times agents registered with the token."
          },
          "last_used_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When an agent last registered with the token; null until one does."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the token was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the token's record last changed. Every registration with it changes it."
          },
          "deleted_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the token was deleted; null while it is not."
          }
        }
      },
      "RegistrationTokenCreate": {
        "type": "object",
        "properties": {
          "organization_id": {
            "type": "string",
            "format": "uuid",
            "description": "The organization whose subtree agents installed with the token register into: this organization or one below it. Installs with a client id that matches no organization below it create one directly under it. Required."
          },
          "label": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 256,
            "description": "A name for the token. Cleaned, as every name is."
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the token stops working; leave it out for a token that does not expire. RFC 3339, an offset and fractions of a second allowed; a past time creates an expired token."
          }
        },
        "required": [
          "organization_id"
        ]
      },
      "RegistrationTokenCreated": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The new registration token's id."
          },
          "token": {
            "type": "string",
            "description": "The token an agent installer presents to register. Keep it secret; it can be read again later by anyone holding `registration_token.reveal`."
          },
          "message": {
            "type": "string",
            "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
          }
        },
        "required": [
          "id",
          "token",
          "message"
        ]
      },
      "RegistrationTokenRevoke": {
        "type": "object",
        "properties": {
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 1024,
            "description": "Why the token is revoked, for whoever reads it later."
          }
        }
      },
      "RegistrationTokenSecret": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string",
            "description": "The token an agent installer presents to register."
          },
          "message": {
            "type": "string",
            "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
          }
        },
        "required": [
          "token",
          "message"
        ]
      },
      "RegistrationTokenUpdate": {
        "type": "object",
        "properties": {
          "label": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 256,
            "description": "The new label. Cleaned, as every name is. `null` or an empty string clears it."
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "The new expiry. Cleared, the token does not expire. `null` or an empty string clears it."
          }
        }
      },
      "ReplicationJobStatus": {
        "type": "object",
        "properties": {
          "last_job_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The id of the latest run."
          },
          "healthy": {
            "type": "boolean",
            "description": "Whether the latest run succeeded."
          },
          "severity": {
            "type": "integer",
            "description": "How serious the latest run's outcome is, on the log severity scale: 9 ok, 13 warning, 17 error, 21 fatal."
          },
          "status": {
            "type": "string",
            "description": "Where the latest run stands."
          },
          "started_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the latest run started."
          },
          "finished_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the latest run finished."
          }
        },
        "required": [
          "last_job_id",
          "healthy",
          "severity",
          "status",
          "started_at",
          "finished_at"
        ]
      },
      "ReplicationTarget": {
        "type": "object",
        "description": "A field not selected with `fields` is absent. A selected field with no value is null.",
        "properties": {
          "id": {
            "type": "string",
            "description": "The target's id."
          },
          "target_type": {
            "type": "string",
            "description": "The kind of storage it is, such as s3, s3_compatible, azure_blob, azure_files, gcs or b2."
          },
          "name": {
            "type": "string",
            "description": "The target's name."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "The target's description; null when it has none."
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether data is copied to the target."
          },
          "scope": {
            "$ref": "#/components/schemas/Scope",
            "description": "Which organizations' data is copied to the target, all or selected. A target saved without organizations copies nothing and reads as selected with none."
          },
          "config": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "The target's storage settings by name, such as bucket, s3_region or azure_container. Settings that are not storage settings are left out, and so is an s3_endpoint carrying a user name or a query. Its contents are not part of the API contract and may change."
          },
          "credential_names": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The names of the credentials stored on the target, such as s3_secret_access_key, in order. The credentials themselves are never sent."
          },
          "job_status": {
            "description": "How the target's latest run went; null until it has run.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/ReplicationJobStatus"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "Role": {
        "type": "object",
        "description": "A field not selected with `fields` is absent. A selected field with no value is null.",
        "properties": {
          "id": {
            "type": "string",
            "description": "The role's id."
          },
          "kind": {
            "type": "string",
            "x-known-values": [
              "standard",
              "custom"
            ],
            "description": "Who defines the role."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "What the role is for."
          },
          "recommended_scope": {
            "type": [
              "string",
              "null"
            ],
            "x-known-values": [
              "all",
              "selected",
              "workspace"
            ],
            "description": "The scope a grant of this role is usually given; null when there is none."
          },
          "sort_order": {
            "type": "integer",
            "description": "Where the role sorts in a list of roles."
          },
          "privileges": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RolePrivilege"
            },
            "description": "Every privilege the role holds."
          }
        }
      },
      "RolePrivilege": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The privilege's id."
          },
          "level": {
            "type": "string",
            "x-known-values": [
              "org",
              "workspace",
              "self"
            ],
            "description": "Where the privilege takes effect."
          },
          "category": {
            "type": [
              "string",
              "null"
            ],
            "description": "The area the privilege belongs to."
          },
          "access_kind": {
            "type": "string",
            "x-known-values": [
              "view",
              "manage"
            ],
            "description": "Whether the privilege reads or changes something."
          }
        },
        "required": [
          "id",
          "level",
          "category",
          "access_kind"
        ]
      },
      "Scope": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "all",
              "selected",
              "workspace"
            ],
            "description": "Which organizations. Required."
          },
          "org_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "With selected, the topmost organizations you can see, sorted; empty otherwise. Every answer sends it. On a write, the organizations it covers: at least one with selected, none otherwise."
          },
          "inherited": {
            "type": "boolean",
            "readOnly": true,
            "description": "True when one of `org_ids` sits below an organization the scope names that you cannot see. Read-only: every answer sends it, and a write ignores it."
          },
          "other_orgs": {
            "type": "boolean",
            "readOnly": true,
            "description": "True when the scope covers organizations you cannot see, which are left out without an id or a count; with all, when you cannot see every organization. Read-only: every answer sends it, and a write ignores it."
          }
        },
        "required": [
          "kind"
        ]
      },
      "ServicePlan": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The plan's id."
          },
          "name": {
            "type": "string",
            "description": "The plan's name."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "The plan's description."
          },
          "sort_order": {
            "type": "integer",
            "description": "Where the plan sorts in a list of plans."
          },
          "data_engine_id": {
            "type": "string",
            "description": "The engine the plan stores and queries data with."
          },
          "is_billable": {
            "type": "boolean",
            "description": "Whether the plan is billed."
          },
          "max_retention_hours": {
            "type": "integer",
            "description": "The longest retention the plan allows, in hours."
          },
          "self_hosted_querying": {
            "type": "boolean",
            "description": "Whether queries run in your own cloud project."
          },
          "allow_custom_query_scanned_limit": {
            "type": "boolean",
            "description": "Whether the workspace may set its own limit on data scanned per query."
          }
        },
        "required": [
          "id",
          "name",
          "description",
          "sort_order",
          "data_engine_id",
          "is_billable",
          "max_retention_hours",
          "self_hosted_querying",
          "allow_custom_query_scanned_limit"
        ]
      },
      "Storage": {
        "type": "object",
        "properties": {
          "gcp_project_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The Google Cloud project holding the workspace's data."
          },
          "gcp_bigquery_dataset": {
            "type": [
              "string",
              "null"
            ],
            "description": "The BigQuery dataset holding the workspace's data."
          },
          "gcp_archive_bucket": {
            "type": [
              "string",
              "null"
            ],
            "description": "The Cloud Storage bucket the workspace archives to."
          },
          "gcp_archive_bucket_prefix": {
            "type": [
              "string",
              "null"
            ],
            "description": "The path inside the archive bucket."
          },
          "gcp_archive_bucket_verified_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When SparkLogs last confirmed it can write to the archive bucket."
          }
        },
        "required": [
          "gcp_project_id",
          "gcp_bigquery_dataset",
          "gcp_archive_bucket",
          "gcp_archive_bucket_prefix",
          "gcp_archive_bucket_verified_at"
        ]
      },
      "Usage": {
        "type": "object",
        "properties": {
          "ingest_quota_bytes": {
            "type": "integer",
            "description": "The workspace's ingest quota, in bytes."
          },
          "ingested_this_month_bytes": {
            "type": "integer",
            "description": "The most ingested so far this month, in bytes. It is sampled, so it can trail the true figure by a few minutes of ingest."
          },
          "custom_query_scanned_limit_mib": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The workspace's own limit on data scanned per query, in MiB; null for the plan's."
          }
        },
        "required": [
          "ingest_quota_bytes",
          "ingested_this_month_bytes",
          "custom_query_scanned_limit_mib"
        ]
      },
      "User": {
        "type": "object",
        "description": "A field not selected with `fields` is absent. A selected field with no value is null.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Your user id."
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Your email address."
          },
          "full_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Your full name."
          },
          "display_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "The name shown for you in the app."
          }
        }
      },
      "Workspace": {
        "type": "object",
        "description": "A field not selected with `fields` is absent. A selected field with no value is null.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The workspace's id."
          },
          "name": {
            "type": "string",
            "description": "The workspace's name."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "The workspace's description."
          },
          "region": {
            "$ref": "#/components/schemas/Region",
            "description": "Where the workspace's data lives."
          },
          "plan": {
            "$ref": "#/components/schemas/ServicePlan",
            "description": "The workspace's service plan."
          },
          "data_initialized": {
            "type": "boolean",
            "description": "Whether the workspace's data storage is set up."
          },
          "retention_hours": {
            "type": "integer",
            "description": "How long log data is kept, in hours."
          },
          "trial_expires_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the workspace's trial ends; null when it has none."
          },
          "app_analytics_provisioned": {
            "type": "boolean",
            "description": "Whether App Analytics is set up."
          },
          "deleted_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the workspace was deleted; null while it is live."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the workspace's record last changed. Every write to it moves this, SparkLogs' own bookkeeping such as recorded ingest usage included, so it moves without any change to settings."
          },
          "usage": {
            "description": "How much the workspace has ingested against its quota. Needs `ingestion.read` across the whole workspace: held on part of the organization tree, naming this field returns 403.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/Usage"
              },
              {
                "type": "null"
              }
            ]
          },
          "storage": {
            "description": "Where the workspace's data and archive are stored. Needs `archive.config.read` across the whole workspace: held on part of the organization tree, naming this field returns 403.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/Storage"
              },
              {
                "type": "null"
              }
            ]
          },
          "settings": {
            "type": [
              "object",
              "null"
            ],
            "description": "The workspace's settings, such as `onboarding` and `ingest_policy`, as an object. Its contents are not part of the API contract and may change."
          },
          "job_statuses": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/JobStatus"
            },
            "description": "The latest run of each of the workspace's background jobs."
          },
          "agent_rollout_ring": {
            "type": [
              "string",
              "null"
            ],
            "description": "Which agent update ring the workspace's agents follow: `canary`, `early_access` or `stable`."
          }
        }
      },
      "WorkspaceUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 128,
            "description": "The new name. Cleaned, as every name is. `null` or an empty string returns 400."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 2048,
            "description": "The new description. `null` or an empty string clears it."
          }
        }
      },
      "WorkspaceUpdated": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
          }
        },
        "required": [
          "message"
        ]
      },
      "WriteResult": {
        "type": "object",
        "properties": {
          "cache_clear_status": {
            "type": [
              "string",
              "null"
            ],
            "x-known-values": [
              "ok",
              "failed",
              "disabled"
            ],
            "description": "Sent when the change has to reach every region's cache: how far it got."
          },
          "cache_clear_message": {
            "type": [
              "string",
              "null"
            ],
            "description": "Sent with a `cache_clear_status` other than ok: what it means, for a person to read."
          },
          "message": {
            "type": "string",
            "description": "What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status."
          }
        },
        "required": [
          "message"
        ]
      },
      "Error": {
        "type": "object",
        "description": "A call that fails returns a JSON body with `error`, a message for a person, and `error_code`, a stable code to act on.",
        "properties": {
          "error": {
            "type": "string",
            "description": "A message for a person."
          },
          "error_code": {
            "type": "string",
            "description": "A stable code to act on."
          },
          "parameter": {
            "type": "string",
            "description": "The parameter, field or path parameter to blame, on a 400, 404 or 409 that names one."
          },
          "privilege": {
            "type": "string",
            "description": "On a privilege refusal, the privilege the call asked about."
          },
          "at_org": {
            "type": "boolean",
            "description": "On a privilege refusal, `true` when it was refused at one organization rather than across the workspace."
          },
          "cause": {
            "type": "string",
            "description": "On an API token's privilege refusal or on a 429, why the call was refused.",
            "x-known-values": [
              "token_scope",
              "no_privilege",
              "call_limit",
              "invalid_token_attempts",
              "send_limit"
            ]
          },
          "required_scope": {
            "type": "string",
            "description": "With `cause` set to `token_scope`, a scope the call needs; when more than one is missing, the next refusal names the next."
          },
          "incident_id": {
            "type": "string",
            "description": "On a 500, an id to quote to support: the server's log of the failure names the same id."
          }
        }
      }
    }
  }
}
