{
  "openapi": "3.1.0",
  "info": {
    "title": "qloudpulse API",
    "version": "1",
    "summary": "Send changes and estimates to qloudpulse, and read your company's own data.",
    "description": "The public API (docs/adr/0127-companies-read-their-own-data-through-api-qloudpulse-com.md), on https://api.qloudpulse.com for hosted companies and on an install's own host when self-hosted. The page for people is https://qloudpulse.com/api-reference.html, made from this file.\n\n**Tokens.** Every route but the estimate catalogue and the contract itself takes one of your company's own tokens as `Authorization: Bearer ...`, never a sign-in: an event source's token or a member's own (`qpev_...`) writes events, estimates and bundles, and an API key (`qpk_...`) reads reports and exports. A token that is missing, malformed, wrong, rotated, expired or removed gets the same 401, which does not say which. No route sets a cookie, and every answer carries `Access-Control-Allow-Origin: *` without credentials.\n\n**Refusals.** Every refusal is RFC 9457 problem details (`application/problem+json`): `type` is a stable URI for the kind of refusal, from the list in `components.x-problems`, `title` names it in English and `detail` says what to change. `POST /v1/events` answers its 400 with the events refused instead.\n\n**Limits.** Each API key may make 60 requests a minute and each company 600, counted in fixed minutes; past either, 429 with `Retry-After` in seconds. An event source may send 600 events a minute and 60 estimates a minute. Bodies are read up to a size per route, and past it the answer is 413. A report read gives at most 10,000 rows, and says `truncated` when the window held more: there is no cursor, so narrow the window, filter, group by less, or ask for an export.\n\n**Data.** Times are ISO 8601 in UTC. Amounts are decimal strings, never rounded, and each measure names its unit (a currency code for money).\n\n**Versions.** /v1 changes only by adding: new routes, new optional fields, new values a client has to ignore. Anything else is /v2, and /v1 keeps answering for a year after /v2 ships, with a `Deprecation` header and a `Sunset` date on every answer.\n\n**Client authors.** Tell refusals apart by `type`, never by `title` or `detail`, which may be reworded; handle a type you do not know by its `status`. Ignore fields you do not know, in every answer. A value listed under `x-extensible-enum` may get new siblings: treat one you do not know as the field's description says, never as an error. Do not hard-code report ids or columns: they follow the app, so read `GET /v1/reports` first and use the `id`, `dimensions` and `measures` it gives. Watch for a `Deprecation` or `Sunset` header, which /v1 will carry for a year before anything is taken away.",
    "contact": {
      "name": "qloudpulse support",
      "email": "support@qloudpulse.com",
      "url": "https://qloudpulse.com/api-reference.html"
    }
  },
  "servers": [
    {
      "url": "https://api.qloudpulse.com",
      "description": "Hosted qloudpulse"
    }
  ],
  "security": [
    {
      "sourceToken": []
    }
  ],
  "paths": {
    "/v1/events": {
      "post": {
        "operationId": "sendEvents",
        "summary": "Send change events",
        "description": "Marks one change on your cost charts, or up to 100 sent together as `{\"events\": [...]}`. A batch is taken whole or not at all: when one event is refused, nothing is taken and the 400 says which and why, so a retry after fixing it adds nothing twice. An event with the same `id` as one already taken replaces it (docs/adr/0117). The body is read up to 1 MB, and a source may send 600 events a minute.",
        "tags": [
          "Events"
        ],
        "security": [
          {
            "sourceToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Event"
                  },
                  {
                    "type": "object",
                    "required": [
                      "events"
                    ],
                    "properties": {
                      "events": {
                        "type": "array",
                        "minItems": 1,
                        "maxItems": 100,
                        "items": {
                          "$ref": "#/components/schemas/Event"
                        }
                      }
                    }
                  }
                ]
              },
              "examples": {
                "one": {
                  "summary": "One event",
                  "value": {
                    "title": "checkout v2.31.0",
                    "type": "release",
                    "service": "checkout",
                    "environment": "prod",
                    "version": "v2.31.0"
                  }
                },
                "batch": {
                  "summary": "Several at once",
                  "value": {
                    "events": [
                      {
                        "title": "checkout v2.31.0",
                        "type": "release",
                        "at": "2026-11-16T08:30:00Z",
                        "service": "checkout",
                        "environment": "prod",
                        "version": "v2.31.0",
                        "url": "https://github.com/example/shop/releases/tag/v2.31.0",
                        "tags": {
                          "team": "payments"
                        },
                        "id": "checkout-v2.31.0-prod"
                      },
                      {
                        "title": "Raise checkout's task count to 6",
                        "type": "config",
                        "service": "checkout",
                        "environment": "prod",
                        "at": "2026-11-16T09:05:00Z"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Taken: every event in the body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Ingested"
                },
                "examples": {
                  "taken": {
                    "summary": "Both events of a batch taken",
                    "value": {
                      "title": "Taken",
                      "taken": 2,
                      "problems": []
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "At least one event was refused, so none was taken: problem details whose `taken` and `problems` members give each refused event's index in `events` (0 for a single event) and its reasons. Fix those and send the whole body again.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Problem"
                    },
                    {
                      "$ref": "#/components/schemas/Ingested"
                    }
                  ]
                },
                "examples": {
                  "refused": {
                    "summary": "The second event has no title",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-events-refused",
                      "title": "Refused: nothing was taken",
                      "status": 400,
                      "detail": "An event was refused, so nothing was taken. problems says which and why: fix it and send the whole body again.",
                      "instance": "/v1/events",
                      "taken": 0,
                      "problems": [
                        {
                          "index": 1,
                          "reasons": [
                            "No \"title\". Every event needs one: it is what the chart's marker says."
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is malformed, wrong, rotated or removed. The answer does not say which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "missing": {
                    "summary": "No token, or not a qpev_ token",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-not-a-source-token",
                      "title": "Not an event source's token",
                      "status": 401,
                      "detail": "Send the source's token as Authorization: Bearer qpev_…, as the Events page showed it.",
                      "instance": "/v1/events"
                    }
                  },
                  "wrong": {
                    "summary": "Not one of your company's tokens",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-not-a-source-token",
                      "title": "Not an event source's token",
                      "status": 401,
                      "detail": "The token is not one of this company's event sources: it may have been rotated or removed.",
                      "instance": "/v1/events"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "The body is over 1 MB.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "refused": {
                    "summary": "Too large",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-too-large",
                      "title": "Too large",
                      "status": 413,
                      "detail": "A request is at most 1 MB. Send up to 100 events at a time, or fewer, and a large apply's resources as several events with the same iac.run and iac.stack.",
                      "instance": "/v1/events"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Past 600 events a minute from this source. Wait a minute and send again; this answer has no `Retry-After`.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "refused": {
                    "summary": "Too many events",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-too-many-events",
                      "title": "Too many events",
                      "status": 429,
                      "detail": "Past 600 events a minute from this source. Wait a minute and send again.",
                      "instance": "/v1/events"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/estimates": {
      "post": {
        "operationId": "estimateChange",
        "summary": "Price an infrastructure change before it is applied",
        "description": "What `qloudpulse estimate` sends from a pipeline (docs/adr/0123): the resources a Pulumi preview or a Terraform or OpenTofu plan changes, with the attributes that set their price, and back comes each one's monthly cost before and after. The request is an `EstimateRequest` and the answer an `EstimateResponse`, the same the `qloudpulse` CLI sends and reads. Ask `POST /v1/estimates/catalogue` first for which attributes to send. A `qloudpulse` client older than the version the install expects, by its `User-Agent`, is refused with a 400 that says which version to get. The body is read up to 1 MB, and a source may ask for 60 estimates a minute.",
        "tags": [
          "Estimates"
        ],
        "security": [
          {
            "sourceToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EstimateRequest"
              },
              "examples": {
                "change": {
                  "summary": "An RDS instance made larger and Multi-AZ, a cache left the same",
                  "value": {
                    "formatVersion": 1,
                    "tool": "pulumi",
                    "stack": "shop/prod",
                    "resources": [
                      {
                        "key": "r3f9a1c2b4d5e6f7a",
                        "name": "orders-db",
                        "urn": "urn:pulumi:prod::shop::aws:rds/instance:Instance::orders-db",
                        "change": "update",
                        "type": "aws:rds/instance:Instance",
                        "region": "eu-north-1",
                        "before": {
                          "instanceClass": "db.r6g.large",
                          "engine": "postgres",
                          "multiAz": false,
                          "allocatedStorage": 100,
                          "storageType": "gp3"
                        },
                        "after": {
                          "instanceClass": "db.r6g.xlarge",
                          "engine": "postgres",
                          "multiAz": true,
                          "allocatedStorage": 100,
                          "storageType": "gp3"
                        },
                        "unknown": []
                      },
                      {
                        "key": "r0c4d8e2f6a1b5c9d",
                        "name": "orders-cache",
                        "urn": "urn:pulumi:prod::shop::aws:elasticache/replicationGroup:ReplicationGroup::orders-cache",
                        "change": "same",
                        "type": "aws:elasticache/replicationGroup:ReplicationGroup",
                        "region": "eu-north-1",
                        "before": {
                          "nodeType": "cache.t4g.small",
                          "numCacheClusters": 2
                        },
                        "after": {
                          "nodeType": "cache.t4g.small",
                          "numCacheClusters": 2
                        },
                        "unknown": []
                      }
                    ],
                    "notPriced": [
                      {
                        "type": "aws:cloudfront/distribution:Distribution",
                        "count": 1
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The change, priced: one answer per resource sent, with its monthly cost before and after in USD. Kept as an estimate with its own page unless the request said `\"store\": false`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EstimateResponse"
                },
                "examples": {
                  "priced": {
                    "summary": "Priced and kept",
                    "value": {
                      "formatVersion": 1,
                      "estimateId": "est_01JD8Y3Q5K7M9P2R4T6V8X0Z1A",
                      "stored": true,
                      "currency": "USD",
                      "url": "https://app.qloudpulse.com/ui/?estimate=est_01JD8Y3Q5K7M9P2R4T6V8X0Z1A",
                      "resources": [
                        {
                          "key": "r3f9a1c2b4d5e6f7a",
                          "monthlyBefore": 186.15,
                          "monthlyAfter": 701.32,
                          "basis": "company-rate",
                          "notes": [
                            {
                              "kind": "usage",
                              "text": "Over the last 14 days orders-db used 22 % of its CPU on average."
                            }
                          ]
                        },
                        {
                          "key": "r0c4d8e2f6a1b5c9d",
                          "monthlyBefore": 47.45,
                          "monthlyAfter": 47.45,
                          "basis": "list-price"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Not an estimate request, or a client too old: `reasons` lists each problem.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "invalid": {
                    "summary": "A formatVersion this endpoint does not read",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-not-an-estimate-request",
                      "title": "Not an estimate request",
                      "status": 400,
                      "detail": "formatVersion must be 1; update the client if it sends another.",
                      "instance": "/v1/estimates",
                      "reasons": [
                        "formatVersion must be 1; update the client if it sends another."
                      ]
                    }
                  },
                  "oldClient": {
                    "summary": "A client older than the install expects",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-update-the-client",
                      "title": "Update the client",
                      "status": 400,
                      "detail": "This client is 0.1.0, and qloudpulse takes 0.2.0 or later. Download 0.5.0 from https://github.com/ulfmansson/qloudpulse-public/releases.",
                      "instance": "/v1/estimates",
                      "reasons": [
                        "This client is 0.1.0, and qloudpulse takes 0.2.0 or later. Download 0.5.0 from https://github.com/ulfmansson/qloudpulse-public/releases."
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is malformed, wrong, rotated or removed. The answer does not say which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "missing": {
                    "summary": "No token, or not a qpev_ token",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-not-a-source-token",
                      "title": "Not an event source's token",
                      "status": 401,
                      "detail": "Send a change-event source's token as Authorization: Bearer qpev_…, as the Events page showed it.",
                      "instance": "/v1/estimates"
                    }
                  },
                  "wrong": {
                    "summary": "Not one of your company's tokens",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-not-a-source-token",
                      "title": "Not an event source's token",
                      "status": 401,
                      "detail": "The token is not one of this company's event sources: it may have been rotated or removed.",
                      "instance": "/v1/estimates"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "The body is over 1 MB.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "refused": {
                    "summary": "Too large",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-too-large",
                      "title": "Too large",
                      "status": 413,
                      "detail": "A request is at most 1 MB. Split the stack's change, or send fewer resources.",
                      "instance": "/v1/estimates"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Past 60 estimates a minute from this source. Wait a minute and send again; this answer has no `Retry-After`.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "refused": {
                    "summary": "Too many estimates",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-too-many-estimates",
                      "title": "Too many estimates",
                      "status": 429,
                      "detail": "Past 60 estimates a minute from this source. Wait a minute and send again.",
                      "instance": "/v1/estimates"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/estimates/catalogue": {
      "post": {
        "operationId": "estimateCatalogue",
        "summary": "What to send for the resource types a preview or a plan found",
        "description": "Name the resource types a preview or a plan found, and get back what the estimates endpoint prices for them and which attributes to send for each. No token: the question holds only type names, and the answer is the same for every company. With `\"tool\": \"terraform\"` or `\"opentofu\"` the types are a plan's, such as `aws_db_instance`, and the answer is in a plan's names. The body is read up to 64 KB and names at most 2,000 types.",
        "tags": [
          "Estimates"
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EstimateCatalogueQuestion"
              },
              "examples": {
                "pulumi": {
                  "summary": "Types from a Pulumi preview",
                  "value": {
                    "formatVersion": 1,
                    "types": [
                      "aws:rds/instance:Instance",
                      "aws:iam/role:Role",
                      "aws:cloudfront/distribution:Distribution"
                    ]
                  }
                },
                "terraform": {
                  "summary": "Types from a Terraform plan",
                  "value": {
                    "formatVersion": 1,
                    "tool": "terraform",
                    "types": [
                      "aws_db_instance",
                      "aws_iam_role"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Of the types asked, those the endpoint prices with the attributes to send, those AWS charges nothing for, the providers whose other types count as not priced, and the client versions this install expects.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EstimateCatalogue"
                },
                "examples": {
                  "pulumi": {
                    "summary": "For the Pulumi types above",
                    "value": {
                      "formatVersion": 1,
                      "providers": [
                        "aws"
                      ],
                      "free": [
                        {
                          "type": "aws:iam/role:Role",
                          "reason": "IAM is offered at no additional charge."
                        }
                      ],
                      "client": {
                        "latest": "0.5.0",
                        "minimum": "0.2.0",
                        "download": "https://github.com/ulfmansson/qloudpulse-public/releases"
                      },
                      "types": [
                        {
                          "type": "aws:rds/instance:Instance",
                          "label": "RDS instance",
                          "attributes": [
                            "instanceClass",
                            "engine",
                            "engineVersion",
                            "licenseModel",
                            "multiAz",
                            "allocatedStorage",
                            "storageType",
                            "iops",
                            "storageThroughput",
                            "backupRetentionPeriod",
                            "performanceInsightsEnabled",
                            "performanceInsightsRetentionPeriod"
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Not a catalogue question.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "refused": {
                    "summary": "Not a catalogue question",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-not-a-catalogue-question",
                      "title": "Not a catalogue question",
                      "status": 400,
                      "detail": "Send {\"formatVersion\": 1, \"types\": [\"aws:rds/instance:Instance\", …]}, at most 2,000 types, or with \"tool\": \"terraform\" or \"opentofu\" a plan's types, such as aws_db_instance.",
                      "instance": "/v1/estimates/catalogue"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "The body is over 64 KB.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "refused": {
                    "summary": "Too large",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-too-large",
                      "title": "Too large",
                      "status": 413,
                      "detail": "Name at most 2,000 types, in 64 KB.",
                      "instance": "/v1/estimates/catalogue"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/reports": {
      "get": {
        "operationId": "listReports",
        "summary": "The reports your company can read",
        "description": "Every report your company can read, as the app lists them, with what each can be grouped by and what it holds. An API key reads everything your company has. Use a report's `id` with `GET /v1/reports/{report}`.",
        "tags": [
          "Reports"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "The reports.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "reports"
                  ],
                  "properties": {
                    "reports": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Report"
                      }
                    }
                  }
                },
                "examples": {
                  "reports": {
                    "summary": "One report of the list",
                    "value": {
                      "reports": [
                        {
                          "id": "aws-cost-by-source",
                          "title": "AWS cost, bill and analysis",
                          "summary": "What AWS cost an hour: the bill for each day it holds whole, our analysis after that.",
                          "group": "Cost now",
                          "provisional": false,
                          "dimensions": [
                            {
                              "column": "account_name",
                              "label": "Account"
                            },
                            {
                              "column": "service",
                              "label": "Service"
                            },
                            {
                              "column": "resource",
                              "label": "Resource"
                            }
                          ],
                          "measures": [
                            {
                              "column": "cost_per_hour",
                              "label": "Cost per hour",
                              "unit": "USD"
                            },
                            {
                              "column": "bill_per_hour",
                              "label": "Bill",
                              "unit": "USD"
                            },
                            {
                              "column": "analysis_per_hour",
                              "label": "Our analysis",
                              "unit": "USD"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/WrongToken"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          }
        }
      }
    },
    "/v1/reports/{report}": {
      "get": {
        "operationId": "reportRows",
        "summary": "A report's rows for a window",
        "description": "The rows the report page's CSV download holds, for the window you ask, grouped and filtered as you ask: JSON, or CSV with `Accept: text/csv`. Rows come oldest first, then by their dimensions. A request gives 1,000 rows, or up to 10,000 with `limit`; an answer cut short has `truncated` true (or the `X-Truncated: true` header in CSV). There is no cursor: narrow the window, filter, group by less, or ask for an export. Amounts are decimal strings, never rounded.",
        "tags": [
          "Reports"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "report",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "A report's `id`, from `GET /v1/reports`.",
            "example": "aws-cost-by-source"
          },
          {
            "name": "from",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "The window's start, inclusive: ISO 8601 with its offset, such as 2026-11-16T00:00:00Z.",
            "example": "2026-11-16T00:00:00Z"
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "The window's end, exclusive. After `from`.",
            "example": "2026-11-18T00:00:00Z"
          },
          {
            "name": "grain",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "hour",
                "day",
                "week",
                "month"
              ],
              "default": "day"
            },
            "description": "How long each row's bucket is."
          },
          {
            "name": "groupBy",
            "in": "query",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "explode": true,
            "description": "A column to group by, from the report's `dimensions`. Repeat for more than one: `groupBy=service&groupBy=account_name`. Without it, one row per bucket.",
            "example": [
              "service"
            ]
          },
          {
            "name": "filter",
            "in": "query",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "explode": true,
            "description": "`<column>:<value>`: keep only rows with that value. Repeat for more.",
            "example": [
              "account_name:production"
            ]
          },
          {
            "name": "exclude",
            "in": "query",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "explode": true,
            "description": "`<column>:<value>`: leave out rows with that value. Repeat for more.",
            "example": [
              "service:Tax"
            ]
          },
          {
            "name": "level",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "For a savings report: `safe`, `balanced` or `aggressive`. Without it, each environment's own level."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10000,
              "default": 1000
            },
            "description": "The most rows to give, 1 to 10,000."
          }
        ],
        "responses": {
          "200": {
            "description": "The rows, as JSON or, with `Accept: text/csv`, as CSV.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Rows"
                },
                "examples": {
                  "rows": {
                    "summary": "Two days, grouped by service",
                    "value": {
                      "report": "aws-cost-by-source",
                      "grain": "day",
                      "from": "2026-11-16T00:00:00Z",
                      "to": "2026-11-18T00:00:00Z",
                      "dimensions": [
                        "service"
                      ],
                      "measures": [
                        {
                          "column": "cost_per_hour",
                          "label": "Cost per hour",
                          "unit": "USD"
                        },
                        {
                          "column": "bill_per_hour",
                          "label": "Bill",
                          "unit": "USD"
                        },
                        {
                          "column": "analysis_per_hour",
                          "label": "Our analysis",
                          "unit": "USD"
                        }
                      ],
                      "rows": [
                        {
                          "bucket": "2026-11-16T00:00:00Z",
                          "dimensions": {
                            "service": "Amazon EC2"
                          },
                          "measures": {
                            "cost_per_hour": "1.2500",
                            "bill_per_hour": "1.2500"
                          }
                        },
                        {
                          "bucket": "2026-11-16T00:00:00Z",
                          "dimensions": {
                            "service": "Amazon RDS"
                          },
                          "measures": {
                            "cost_per_hour": "0.4120",
                            "bill_per_hour": "0.4120"
                          }
                        },
                        {
                          "bucket": "2026-11-17T00:00:00Z",
                          "dimensions": {
                            "service": "Amazon EC2"
                          },
                          "measures": {
                            "cost_per_hour": "1.3125",
                            "analysis_per_hour": "1.3125"
                          }
                        },
                        {
                          "bucket": "2026-11-17T00:00:00Z",
                          "dimensions": {
                            "service": "Amazon RDS"
                          },
                          "measures": {
                            "cost_per_hour": "0.4120",
                            "analysis_per_hour": "0.4120"
                          }
                        }
                      ],
                      "truncated": false
                    }
                  }
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                },
                "examples": {
                  "rows": {
                    "summary": "The same rows as CSV",
                    "value": "bucket,service,cost_per_hour,bill_per_hour,analysis_per_hour\r\n2026-11-16T00:00:00Z,Amazon EC2,1.2500,1.2500,\r\n2026-11-16T00:00:00Z,Amazon RDS,0.4120,0.4120,\r\n2026-11-17T00:00:00Z,Amazon EC2,1.3125,,1.3125\r\n2026-11-17T00:00:00Z,Amazon RDS,0.4120,,0.4120\r\n"
                  }
                }
              }
            },
            "headers": {
              "X-Truncated": {
                "description": "In CSV only: `true` when the window held more rows than `limit`.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true",
                    "false"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The query was refused (`invalid-report-query`), or a parameter is missing or not of its type (`invalid-request`); `detail` says why. Checked before the key, so a bad query with a bad key is answered 400.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "window": {
                    "summary": "from after to",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-invalid-report-query",
                      "title": "Invalid report query",
                      "status": 400,
                      "detail": "from must come before to.",
                      "instance": "/v1/reports/aws-cost-by-source"
                    }
                  },
                  "limit": {
                    "summary": "limit too large",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-invalid-report-query",
                      "title": "Invalid report query",
                      "status": 400,
                      "detail": "limit must be between 1 and 10000. For more, narrow the window or filter.",
                      "instance": "/v1/reports/aws-cost-by-source"
                    }
                  },
                  "missing": {
                    "summary": "A required parameter left out",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-invalid-request",
                      "title": "Invalid request",
                      "status": 400,
                      "detail": "Required parameter 'from' is not present.",
                      "instance": "/v1/reports/aws-cost-by-source"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/WrongToken"
          },
          "404": {
            "description": "No such report, or one your company cannot read.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "notFound": {
                    "summary": "No such report",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-report-not-found",
                      "title": "Report not found",
                      "status": 404,
                      "detail": "No report aws-cost-per-tenant",
                      "instance": "/v1/reports/aws-cost-per-tenant"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "The report's definition cannot be read: in a format this install does not read yet, or with problems.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "invalid": {
                    "summary": "A definition with problems",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-invalid-report-definition",
                      "title": "Invalid report definition",
                      "status": 422,
                      "detail": "measures[1].column bill_per_hour is not a column of the view",
                      "instance": "/v1/reports/aws-cost-by-source",
                      "reportStatus": "invalid",
                      "problems": [
                        "measures[1].column bill_per_hour is not a column of the view"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          },
          "503": {
            "description": "Your company's own storage did not answer, or the report's archive is busy. Try again; `detail` says what to check.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "storage": {
                    "summary": "Your own storage",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-storage-unreachable",
                      "title": "Your storage cannot be reached",
                      "status": 503,
                      "detail": "Your storage cannot be reached: STS did not answer (SdkClientException). Check the role qloudpulse-storage, the key alias/qloudpulse-data, that the database qloudpulse-data is available, and its security group.",
                      "instance": "/v1/reports/aws-cost-by-source"
                    }
                  },
                  "archive": {
                    "summary": "The archive busy",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-archive-busy",
                      "title": "Report archive busy",
                      "status": 503,
                      "detail": "The archive of aws_cost_by_source is busy: try again shortly",
                      "instance": "/v1/reports/aws-cost-by-source"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/exports": {
      "post": {
        "operationId": "requestExport",
        "summary": "Ask for an export",
        "description": "Builds the file in the background and answers 202 at once; poll `GET /v1/exports/{id}` (the `Location`) until it is `ready`, then download `GET /v1/exports/{id}/file`. `focus` is your bill, every cloud in it, as FOCUS 1.0 at day grain, one gzipped CSV; FOCUS columns qloudpulse does not hold (resource, SKU, quantity, pricing, commitment discount) are empty. `everything` is one zip: every report's rows by day, the FOCUS bill, change events, budgets, allocation rules, chargeback statements and a README. One export at a time per company; whole months, at most 13; a file is kept 7 days and is at most 50 MB compressed, past which the export fails and says to ask for fewer months.",
        "tags": [
          "Exports"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "kind",
                  "from",
                  "to"
                ],
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "focus",
                      "everything"
                    ],
                    "description": "`focus`: the bill as FOCUS 1.0. `everything`: all of it, as a zip."
                  },
                  "from": {
                    "type": "string",
                    "pattern": "^[0-9]{4}-[0-9]{2}$",
                    "description": "The first month, such as 2026-01."
                  },
                  "to": {
                    "type": "string",
                    "pattern": "^[0-9]{4}-[0-9]{2}$",
                    "description": "The last month, whole: this month at the latest, at most 12 after from."
                  }
                }
              },
              "examples": {
                "focus": {
                  "summary": "Ten months of the bill as FOCUS",
                  "value": {
                    "kind": "focus",
                    "from": "2026-01",
                    "to": "2026-10"
                  }
                },
                "everything": {
                  "summary": "Everything, for the last three months",
                  "value": {
                    "kind": "everything",
                    "from": "2026-09",
                    "to": "2026-11"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Asked for; `Location` is the export.",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "examples": [
                    "/v1/exports/0b6f3c1e-8d2a-4c57-9e11-5a7d2f4b9c30"
                  ]
                },
                "description": "The export's path, for `GET /v1/exports/{id}`."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Export"
                },
                "examples": {
                  "queued": {
                    "summary": "Asked for, waiting to be built",
                    "value": {
                      "id": "0b6f3c1e-8d2a-4c57-9e11-5a7d2f4b9c30",
                      "kind": "focus",
                      "from": "2026-01",
                      "to": "2026-10",
                      "state": "queued",
                      "reason": null,
                      "requestedAt": "2026-11-17T09:12:03Z",
                      "startedAt": null,
                      "finishedAt": null,
                      "expiresAt": "2026-11-24T09:12:03Z",
                      "fileName": null,
                      "sizeBytes": null,
                      "file": null
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Not an export: `detail` says why.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "tooLong": {
                    "summary": "More than 13 months",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-not-an-export",
                      "title": "Not an export",
                      "status": 400,
                      "detail": "An export covers at most 13 months; ask for fewer.",
                      "instance": "/v1/exports"
                    }
                  },
                  "month": {
                    "summary": "Not a month",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-not-an-export",
                      "title": "Not an export",
                      "status": 400,
                      "detail": "from is a month, such as 2026-01.",
                      "instance": "/v1/exports"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/WrongToken"
          },
          "409": {
            "description": "Another of your company's exports is being built.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "busy": {
                    "summary": "One is being built",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-export-busy",
                      "title": "An export is being built",
                      "status": 409,
                      "detail": "Your company has an export being built already; ask again when it is ready or has failed.",
                      "instance": "/v1/exports"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          }
        }
      },
      "get": {
        "operationId": "listExports",
        "summary": "Your company's exports, newest first",
        "tags": [
          "Exports"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "The last 20.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "exports"
                  ],
                  "properties": {
                    "exports": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Export"
                      }
                    }
                  }
                },
                "examples": {
                  "exports": {
                    "summary": "One ready export",
                    "value": {
                      "exports": [
                        {
                          "id": "0b6f3c1e-8d2a-4c57-9e11-5a7d2f4b9c30",
                          "kind": "focus",
                          "from": "2026-01",
                          "to": "2026-10",
                          "state": "ready",
                          "reason": null,
                          "requestedAt": "2026-11-17T09:12:03Z",
                          "startedAt": "2026-11-17T09:12:04Z",
                          "finishedAt": "2026-11-17T09:13:41Z",
                          "expiresAt": "2026-11-24T09:12:03Z",
                          "fileName": "qloudpulse-k3x9d2mq7pwa-focus-2026-01_2026-10.csv.gz",
                          "sizeBytes": 4818233,
                          "file": "/v1/exports/0b6f3c1e-8d2a-4c57-9e11-5a7d2f4b9c30/file"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/WrongToken"
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          }
        },
        "description": "Your company's last 20 exports, newest first."
      }
    },
    "/v1/exports/{id}": {
      "get": {
        "operationId": "getExport",
        "summary": "Where an export stands",
        "tags": [
          "Exports"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The export's `id`, from `POST /v1/exports` or `GET /v1/exports`.",
            "example": "0b6f3c1e-8d2a-4c57-9e11-5a7d2f4b9c30"
          }
        ],
        "responses": {
          "200": {
            "description": "The export.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Export"
                },
                "examples": {
                  "ready": {
                    "summary": "Ready to download",
                    "value": {
                      "id": "0b6f3c1e-8d2a-4c57-9e11-5a7d2f4b9c30",
                      "kind": "focus",
                      "from": "2026-01",
                      "to": "2026-10",
                      "state": "ready",
                      "reason": null,
                      "requestedAt": "2026-11-17T09:12:03Z",
                      "startedAt": "2026-11-17T09:12:04Z",
                      "finishedAt": "2026-11-17T09:13:41Z",
                      "expiresAt": "2026-11-24T09:12:03Z",
                      "fileName": "qloudpulse-k3x9d2mq7pwa-focus-2026-01_2026-10.csv.gz",
                      "sizeBytes": 4818233,
                      "file": "/v1/exports/0b6f3c1e-8d2a-4c57-9e11-5a7d2f4b9c30/file"
                    }
                  },
                  "failed": {
                    "summary": "Failed",
                    "value": {
                      "id": "0b6f3c1e-8d2a-4c57-9e11-5a7d2f4b9c30",
                      "kind": "focus",
                      "from": "2026-01",
                      "to": "2026-10",
                      "state": "failed",
                      "reason": "The export is larger than 50 MB compressed; ask for fewer months.",
                      "requestedAt": "2026-11-17T09:12:03Z",
                      "startedAt": "2026-11-17T09:12:04Z",
                      "finishedAt": "2026-11-17T09:14:10Z",
                      "expiresAt": "2026-11-24T09:12:03Z",
                      "fileName": null,
                      "sizeBytes": null,
                      "file": null
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/WrongToken"
          },
          "404": {
            "description": "No such export, or one past its 7 days.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "notFound": {
                    "summary": "Unknown or expired",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-no-such-export",
                      "title": "No such export",
                      "status": 404,
                      "detail": "Your company has no export with that id, or it is past its 7 days.",
                      "instance": "/v1/exports/0b6f3c1e-8d2a-4c57-9e11-5a7d2f4b9c30"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          }
        },
        "description": "Where an export stands. Poll it, every few seconds, until `state` is `ready` or `failed`."
      }
    },
    "/v1/exports/{id}/file": {
      "get": {
        "operationId": "downloadExport",
        "summary": "A ready export's file",
        "tags": [
          "Exports"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The export's `id`, from `POST /v1/exports` or `GET /v1/exports`.",
            "example": "0b6f3c1e-8d2a-4c57-9e11-5a7d2f4b9c30"
          }
        ],
        "responses": {
          "200": {
            "description": "The file, as an attachment.",
            "content": {
              "application/gzip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            },
            "headers": {
              "Content-Disposition": {
                "description": "The file's name.",
                "schema": {
                  "type": "string",
                  "examples": [
                    "attachment; filename=\"qloudpulse-k3x9d2mq7pwa-focus-2026-01_2026-10.csv.gz\""
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/WrongToken"
          },
          "404": {
            "description": "No such export, or one past its 7 days.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "notFound": {
                    "summary": "Unknown or expired",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-no-such-export",
                      "title": "No such export",
                      "status": 404,
                      "detail": "Your company has no export with that id, or it is past its 7 days.",
                      "instance": "/v1/exports/0b6f3c1e-8d2a-4c57-9e11-5a7d2f4b9c30/file"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "The export is not ready: queued, building or failed.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "notReady": {
                    "summary": "Still building",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-export-not-ready",
                      "title": "Not ready",
                      "status": 409,
                      "detail": "The export is building; its file is there once it is ready.",
                      "instance": "/v1/exports/0b6f3c1e-8d2a-4c57-9e11-5a7d2f4b9c30/file"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooMany"
          }
        },
        "description": "The file of a `ready` export, with the same key, as an attachment: `application/gzip` for `focus`, `application/zip` for `everything`. Save it under the name in `Content-Disposition`."
      }
    },
    "/v1/collection-bundles": {
      "post": {
        "operationId": "uploadCollectionBundle",
        "summary": "Upload an offline collection bundle",
        "description": "A bundle `qloudpulse-collect` packed for AWS accounts your company collects from offline bundles (docs/adr/0141, docs/adr/0142), as the body: the `.tgz` as `application/gzip`, or the `.jwe` from `pack --encrypt` as `application/jose`. It takes the same tokens as `/v1/estimates`: a member's own token (Your tokens, or `qloudpulse login`) or an event source's token, and only an admin's: a member's own token whose owner is not an admin of the company is refused with 403. Checked as it arrives: the manifest's SHA-256s, `schema_version` (the current major and the one before), every recorded operation against the call plan, every account against the bundle's `source_id`, the bill only from its payer account's source, and a window at most 13 days old. Up to 64 MiB as sent.",
        "tags": [
          "Offline collection"
        ],
        "security": [
          {
            "sourceToken": []
          }
        ],
        "parameters": [
          {
            "name": "x-qloudpulse-bundle-schema",
            "in": "header",
            "required": false,
            "description": "The bundle's `schema_version`, so an unknown major is refused before the body is read.",
            "schema": {
              "type": "string"
            },
            "example": "1.0"
          },
          {
            "name": "x-qloudpulse-bundle-sha256",
            "in": "header",
            "required": false,
            "description": "The SHA-256 of the body, lower-case hex; a body that does not match is refused as changed on the way.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}$"
            },
            "example": "9f2c5e1d7a3b4c6e8f0a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/gzip": {
              "schema": {
                "type": "string",
                "contentMediaType": "application/gzip"
              }
            },
            "application/jose": {
              "schema": {
                "type": "string",
                "contentMediaType": "application/jose"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Taken.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BundleReceived"
                },
                "examples": {
                  "stored": {
                    "summary": "Checked and kept",
                    "value": {
                      "reference": "4e1a9c07b3d25f86e0a1",
                      "outcome": "stored"
                    }
                  },
                  "encrypted": {
                    "summary": "A .jwe, kept as it came",
                    "value": {
                      "reference": "9b20d4c6e81f3a5d7c02",
                      "outcome": "encrypted"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "No token, or one that is malformed, wrong, expired or removed, or whose owner left. The answer carries `WWW-Authenticate: Bearer` and does not say which.",
            "headers": {
              "WWW-Authenticate": {
                "schema": {
                  "type": "string",
                  "examples": [
                    "Bearer"
                  ]
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "wrong": {
                    "summary": "Not one of your company's tokens",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-not-your-token",
                      "title": "Not your token",
                      "status": 401,
                      "detail": "The token is not one of this company's: it may have expired, been removed, or its owner left. Run qloudpulse login again, or make one under Your tokens.",
                      "instance": "/v1/collection-bundles"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The token is a member's own, and its owner is not an admin of the company: only admins upload bundles.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "member": {
                    "summary": "A member's own token",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-admins-only",
                      "title": "Admins only",
                      "status": 403,
                      "detail": "Only your company's admins upload bundles. Use an admin's own token, or an event source an admin made under Settings, Events.",
                      "instance": "/v1/collection-bundles"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Your company is not taking bundles: offline collection is not open to it, or not turned on here.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "notOpen": {
                    "summary": "Not open to the company",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-not-taking-bundles",
                      "title": "Not taking bundles",
                      "status": 404,
                      "detail": "Offline collection is not open to your company yet.",
                      "instance": "/v1/collection-bundles"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "This source already delivered this window; the client counts the bundle as delivered.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "delivered": {
                    "summary": "Sent twice",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-already-delivered",
                      "title": "Already delivered",
                      "status": 409,
                      "detail": "Source dc-stockholm already delivered the window starting 2026-11-21T00:00:00Z.",
                      "instance": "/v1/collection-bundles"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "The bundle is over 64 MiB as sent.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "refused": {
                    "summary": "Bundle too large",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-bundle-too-large",
                      "title": "Bundle too large",
                      "status": 413,
                      "detail": "The bundle is larger than 64 MiB. Collect fewer accounts or regions per source.",
                      "instance": "/v1/collection-bundles"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "Neither application/gzip nor application/jose.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "wrongType": {
                    "summary": "Another content type",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-not-a-bundle",
                      "title": "Not a bundle",
                      "status": 415,
                      "detail": "Send the bundle as application/gzip (a .tgz) or application/jose (a .jwe).",
                      "instance": "/v1/collection-bundles"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "A check failed; `detail` says which and what to fix. Nothing of the bundle is kept.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "account": {
                    "summary": "An account not set to offline bundles",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-bundle-refused",
                      "title": "Bundle refused",
                      "status": 422,
                      "detail": "Your company does not collect 210987654321 from offline bundles. Add it on the AWS accounts page as Offline bundles with source dc-stockholm.",
                      "instance": "/v1/collection-bundles"
                    }
                  },
                  "old": {
                    "summary": "A window too old",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-bundle-refused",
                      "title": "Bundle refused",
                      "status": 422,
                      "detail": "The bundle's window starts at 2026-11-01T00:00:00Z, more than 13 days ago. qloudpulse keeps hourly data 14 days, so it would be gone at once.",
                      "instance": "/v1/collection-bundles"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "The bundle could not be handed on to be checked; send it again later.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "later": {
                    "summary": "Try again later",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-not-handed-on",
                      "title": "Try again",
                      "status": 502,
                      "detail": "The bundle could not be handed on to be checked. Send it again later.",
                      "instance": "/v1/collection-bundles"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Your company's members could not be read, to check that the token's owner is an admin. Send the bundle again in a minute.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "later": {
                    "summary": "Try again in a minute",
                    "value": {
                      "type": "https://qloudpulse.com/api-reference.html#problem-members-unavailable",
                      "title": "Try again",
                      "status": 503,
                      "detail": "Your company's members could not be read just now. Send the bundle again in a minute.",
                      "instance": "/v1/collection-bundles"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/openapi.json": {
      "get": {
        "operationId": "contract",
        "summary": "This contract",
        "tags": [
          "API"
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "The OpenAPI document you are reading.",
            "content": {
              "application/json": {}
            }
          }
        },
        "description": "This file: OpenAPI 3.1, open without a token. Point a client generator or an AI assistant at it. Cached for an hour."
      }
    }
  },
  "components": {
    "securitySchemes": {
      "sourceToken": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "qpev_<company>.<token id>.<secret>",
        "description": "An event source's token, made and rotated by an admin on Settings > Events and shown once, or a member's own token, made under Your tokens or by `qloudpulse login`. Sent as `Authorization: Bearer qpev_...`. It writes events, estimates and, an admin's, offline collection bundles, and reads nothing, so a pipeline's token that leaks cannot read your costs."
      },
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "qpk_<company>.<key id>.<secret>",
        "description": "An API key, made and rotated by an admin under Settings > API keys and shown once. Sent as `Authorization: Bearer qpk_...`. It reads everything your company has, writes nothing, and expires within a year. At most 60 requests a minute per key and 600 per company."
      }
    },
    "schemas": {
      "Event": {
        "type": "object",
        "required": [
          "title"
        ],
        "properties": {
          "title": {
            "type": "string",
            "maxLength": 200,
            "description": "What the marker says. Up to 200 characters."
          },
          "type": {
            "type": "string",
            "enum": [
              "release",
              "deploy",
              "incident",
              "config",
              "other"
            ],
            "description": "What kind of change. Without it, the source's kind. This list is what the route takes; it may take more in /v1, so a client that reads events back must expect types it does not know."
          },
          "at": {
            "type": "string",
            "format": "date-time",
            "description": "When it happened, with its offset, from 30 days back to an hour ahead. Without it, when it arrived."
          },
          "service": {
            "type": "string",
            "maxLength": 100,
            "description": "What changed; matched to the source's service tag."
          },
          "environment": {
            "type": "string",
            "maxLength": 100,
            "description": "Where; matched to the source's environment tag."
          },
          "version": {
            "type": "string",
            "maxLength": 100,
            "description": "The release, tag or commit."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://",
            "maxLength": 2000,
            "description": "The marker links to it. https only."
          },
          "tags": {
            "type": "object",
            "maxProperties": 20,
            "additionalProperties": {
              "type": "string"
            },
            "description": "Your own; a tag with a cost tag's name is matched too."
          },
          "id": {
            "type": "string",
            "maxLength": 100,
            "description": "Your own key for the event: one sent again with the same id replaces it, so a retry adds nothing twice."
          },
          "iac": {
            "type": "object",
            "description": "What an infrastructure-as-code change touched, up to 1,000 resources, so the change can be followed to the cost it caused (docs/adr/0124). `qloudpulse` writes it; the Events page shows its fields."
          }
        },
        "additionalProperties": true,
        "description": "One change, marked on the cost charts. Only `title` is required. Fields the endpoint does not read are dropped.",
        "examples": [
          {
            "title": "checkout v2.31.0",
            "type": "release",
            "at": "2026-11-16T08:30:00Z",
            "service": "checkout",
            "environment": "prod",
            "version": "v2.31.0",
            "url": "https://github.com/example/shop/releases/tag/v2.31.0",
            "tags": {
              "team": "payments"
            },
            "id": "checkout-v2.31.0-prod"
          }
        ]
      },
      "Ingested": {
        "type": "object",
        "required": [
          "taken"
        ],
        "properties": {
          "title": {
            "type": "string",
            "description": "`Taken`, or `Refused: nothing was taken`."
          },
          "taken": {
            "type": "integer",
            "minimum": 0,
            "description": "How many events were taken: 0 on a 400."
          },
          "problems": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "index",
                "reasons"
              ],
              "properties": {
                "index": {
                  "type": "integer",
                  "minimum": 0
                },
                "reasons": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            },
            "description": "On a 400, one entry per refused event."
          }
        },
        "description": "What `POST /v1/events` answers: how many events were taken, and for a 400 each refused event's place in `events` (0 for a single event) and why. A batch is taken whole or not at all.",
        "examples": [
          {
            "title": "Taken",
            "taken": 2,
            "problems": []
          }
        ]
      },
      "Problem": {
        "type": "object",
        "description": "A refusal, as RFC 9457 problem details, sent as `application/problem+json`. Read `status` and `title` in code and show `detail` to people: it says what to change. Other members may be added; ignore those you do not know.",
        "properties": {
          "type": {
            "type": "string",
            "description": "What kind of refusal it is: a URI from `components.x-problems`, each an anchor on the API reference that says what it means. Tell refusals apart by it, not by `title`. A type keeps its meaning; new ones may be added, so handle one you do not know by its `status`.",
            "format": "uri",
            "x-extensible-enum": [
              "https://qloudpulse.com/api-reference.html#problem-not-an-api-key",
              "https://qloudpulse.com/api-reference.html#problem-rate-limited",
              "https://qloudpulse.com/api-reference.html#problem-not-a-source-token",
              "https://qloudpulse.com/api-reference.html#problem-too-large",
              "https://qloudpulse.com/api-reference.html#problem-too-many-events",
              "https://qloudpulse.com/api-reference.html#problem-events-refused",
              "https://qloudpulse.com/api-reference.html#problem-not-a-catalogue-question",
              "https://qloudpulse.com/api-reference.html#problem-update-the-client",
              "https://qloudpulse.com/api-reference.html#problem-not-an-estimate-request",
              "https://qloudpulse.com/api-reference.html#problem-too-many-estimates",
              "https://qloudpulse.com/api-reference.html#problem-not-your-token",
              "https://qloudpulse.com/api-reference.html#problem-admins-only",
              "https://qloudpulse.com/api-reference.html#problem-not-taking-bundles",
              "https://qloudpulse.com/api-reference.html#problem-already-delivered",
              "https://qloudpulse.com/api-reference.html#problem-bundle-too-large",
              "https://qloudpulse.com/api-reference.html#problem-not-a-bundle",
              "https://qloudpulse.com/api-reference.html#problem-bundle-refused",
              "https://qloudpulse.com/api-reference.html#problem-not-handed-on",
              "https://qloudpulse.com/api-reference.html#problem-members-unavailable",
              "https://qloudpulse.com/api-reference.html#problem-not-an-export",
              "https://qloudpulse.com/api-reference.html#problem-no-such-export",
              "https://qloudpulse.com/api-reference.html#problem-export-busy",
              "https://qloudpulse.com/api-reference.html#problem-export-not-ready",
              "https://qloudpulse.com/api-reference.html#problem-invalid-report-query",
              "https://qloudpulse.com/api-reference.html#problem-report-not-found",
              "https://qloudpulse.com/api-reference.html#problem-unsupported-report-format",
              "https://qloudpulse.com/api-reference.html#problem-invalid-report-definition",
              "https://qloudpulse.com/api-reference.html#problem-storage-unreachable",
              "https://qloudpulse.com/api-reference.html#problem-archive-busy",
              "https://qloudpulse.com/api-reference.html#problem-invalid-request",
              "https://qloudpulse.com/api-reference.html#problem-no-such-route",
              "https://qloudpulse.com/api-reference.html#problem-method-not-allowed",
              "https://qloudpulse.com/api-reference.html#problem-not-acceptable",
              "https://qloudpulse.com/api-reference.html#problem-unsupported-media-type"
            ]
          },
          "title": {
            "type": "string",
            "description": "What went wrong, short and the same for every case of it."
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status code."
          },
          "detail": {
            "type": "string",
            "description": "This case: what was refused and what to change."
          },
          "instance": {
            "type": "string",
            "description": "The path that was asked for."
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "On `POST /v1/estimates`, each reason the request was refused, on its own."
          }
        },
        "examples": [
          {
            "type": "https://qloudpulse.com/api-reference.html#problem-invalid-report-query",
            "title": "Invalid report query",
            "status": 400,
            "detail": "from must come before to.",
            "instance": "/v1/reports/aws-cost-by-source"
          }
        ]
      },
      "Measure": {
        "type": "object",
        "required": [
          "column",
          "label"
        ],
        "properties": {
          "column": {
            "type": "string",
            "description": "Its key in each row's `measures`, and its CSV column."
          },
          "label": {
            "type": "string",
            "description": "What the app calls it."
          },
          "unit": {
            "type": [
              "string",
              "null"
            ],
            "description": "A currency code (ISO 4217) for money, else the definition's unit, or null."
          }
        },
        "description": "A figure a report's rows hold.",
        "examples": [
          {
            "column": "cost_per_hour",
            "label": "Cost per hour",
            "unit": "USD"
          }
        ]
      },
      "Report": {
        "type": "object",
        "required": [
          "id",
          "title",
          "dimensions",
          "measures"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Its id, for `GET /v1/reports/{report}`. Ids follow the app's reports, which are published as qloudpulse adds and improves them: one may be renamed or removed, so read the list rather than keep ids."
          },
          "title": {
            "type": "string",
            "description": "Its name in the app."
          },
          "summary": {
            "type": [
              "string",
              "null"
            ],
            "description": "What it shows, in a sentence."
          },
          "group": {
            "type": [
              "string",
              "null"
            ],
            "description": "The heading the app lists it under."
          },
          "provisional": {
            "type": "boolean",
            "description": "True while its figures may still change, such as before the bill holds the day."
          },
          "dimensions": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "column",
                "label"
              ],
              "properties": {
                "column": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                }
              }
            },
            "description": "What its rows can be grouped by (`groupBy`) and filtered on (`filter`, `exclude`). Columns follow the report's definition and may change with it."
          },
          "measures": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Measure"
            },
            "description": "What its rows hold, each with its unit. Columns follow the report's definition and may change with it."
          }
        },
        "description": "A report your company can read: what its rows can be grouped by, and what they hold.",
        "examples": [
          {
            "id": "aws-cost-by-source",
            "title": "AWS cost, bill and analysis",
            "summary": "What AWS cost an hour: the bill for each day it holds whole, our analysis after that.",
            "group": "Cost now",
            "provisional": false,
            "dimensions": [
              {
                "column": "account_name",
                "label": "Account"
              },
              {
                "column": "service",
                "label": "Service"
              },
              {
                "column": "resource",
                "label": "Resource"
              }
            ],
            "measures": [
              {
                "column": "cost_per_hour",
                "label": "Cost per hour",
                "unit": "USD"
              },
              {
                "column": "bill_per_hour",
                "label": "Bill",
                "unit": "USD"
              },
              {
                "column": "analysis_per_hour",
                "label": "Our analysis",
                "unit": "USD"
              }
            ]
          }
        ]
      },
      "Rows": {
        "type": "object",
        "required": [
          "report",
          "grain",
          "from",
          "to",
          "dimensions",
          "measures",
          "rows",
          "truncated"
        ],
        "properties": {
          "report": {
            "type": "string",
            "description": "The report's id."
          },
          "grain": {
            "type": "string",
            "description": "How long each row's bucket is. More values may be added in /v1: treat one you do not know as the grain you asked for.",
            "x-extensible-enum": [
              "hour",
              "day",
              "week",
              "month"
            ]
          },
          "from": {
            "type": "string",
            "format": "date-time",
            "description": "The window's start, as asked."
          },
          "to": {
            "type": "string",
            "format": "date-time",
            "description": "The window's end, as asked."
          },
          "dimensions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The columns the rows are grouped by, as asked."
          },
          "measures": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Measure"
            },
            "description": "What each row holds, in the report's order."
          },
          "rows": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "bucket",
                "dimensions",
                "measures"
              ],
              "properties": {
                "bucket": {
                  "type": "string",
                  "format": "date-time",
                  "description": "The start of the row's hour, day, week or month."
                },
                "dimensions": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "The row's value of each column grouped by."
                },
                "measures": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "string",
                    "pattern": "^-?[0-9]+(\\.[0-9]+)?$"
                  },
                  "description": "Each measure as a decimal string; one with no value is left out."
                }
              }
            },
            "description": "The rows. A row with no value for a measure leaves it out."
          },
          "truncated": {
            "type": "boolean",
            "description": "True when the window held more rows than `limit`: this is not all of it."
          }
        },
        "description": "A report's rows for a window, oldest first, then by their dimensions in the order asked, so the same question gets the same answer.",
        "examples": [
          {
            "report": "aws-cost-by-source",
            "grain": "day",
            "from": "2026-11-16T00:00:00Z",
            "to": "2026-11-18T00:00:00Z",
            "dimensions": [
              "service"
            ],
            "measures": [
              {
                "column": "cost_per_hour",
                "label": "Cost per hour",
                "unit": "USD"
              },
              {
                "column": "bill_per_hour",
                "label": "Bill",
                "unit": "USD"
              },
              {
                "column": "analysis_per_hour",
                "label": "Our analysis",
                "unit": "USD"
              }
            ],
            "rows": [
              {
                "bucket": "2026-11-16T00:00:00Z",
                "dimensions": {
                  "service": "Amazon EC2"
                },
                "measures": {
                  "cost_per_hour": "1.2500",
                  "bill_per_hour": "1.2500"
                }
              },
              {
                "bucket": "2026-11-16T00:00:00Z",
                "dimensions": {
                  "service": "Amazon RDS"
                },
                "measures": {
                  "cost_per_hour": "0.4120",
                  "bill_per_hour": "0.4120"
                }
              },
              {
                "bucket": "2026-11-17T00:00:00Z",
                "dimensions": {
                  "service": "Amazon EC2"
                },
                "measures": {
                  "cost_per_hour": "1.3125",
                  "analysis_per_hour": "1.3125"
                }
              },
              {
                "bucket": "2026-11-17T00:00:00Z",
                "dimensions": {
                  "service": "Amazon RDS"
                },
                "measures": {
                  "cost_per_hour": "0.4120",
                  "analysis_per_hour": "0.4120"
                }
              }
            ],
            "truncated": false
          }
        ]
      },
      "Export": {
        "type": "object",
        "required": [
          "id",
          "kind",
          "from",
          "to",
          "state",
          "requestedAt",
          "expiresAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Its id, for `GET /v1/exports/{id}`."
          },
          "kind": {
            "type": "string",
            "description": "`focus`: the bill as FOCUS 1.0. `everything`: one zip of all of it. More values may be added in /v1: treat one you do not know as a kind of file you do not read.",
            "x-extensible-enum": [
              "focus",
              "everything"
            ]
          },
          "from": {
            "type": "string",
            "description": "The first month, such as 2026-01."
          },
          "to": {
            "type": "string",
            "description": "The last month, whole."
          },
          "state": {
            "type": "string",
            "description": "Where it stands. Poll `GET /v1/exports/{id}` until it is `ready` or `failed`. More values may be added in /v1: treat one you do not know as not ready yet, and keep polling until `finishedAt` is set.",
            "x-extensible-enum": [
              "queued",
              "building",
              "ready",
              "failed"
            ]
          },
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why it failed."
          },
          "requestedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When it was asked for."
          },
          "startedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When its build started."
          },
          "finishedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When its build ended, ready or failed."
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "description": "When it and its file are deleted, 7 days after it was asked for."
          },
          "fileName": {
            "type": [
              "string",
              "null"
            ],
            "description": "The file's name, once it is ready."
          },
          "sizeBytes": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The file's size in bytes, compressed, once it is ready."
          },
          "file": {
            "type": [
              "string",
              "null"
            ],
            "description": "Where to download it, with the same key, once it is ready; a path on this host."
          }
        },
        "description": "An export and where it stands: `queued`, then `building`, then `ready` or `failed`. Kept 7 days from when it was asked for.",
        "examples": [
          {
            "id": "0b6f3c1e-8d2a-4c57-9e11-5a7d2f4b9c30",
            "kind": "focus",
            "from": "2026-01",
            "to": "2026-10",
            "state": "ready",
            "reason": null,
            "requestedAt": "2026-11-17T09:12:03Z",
            "startedAt": "2026-11-17T09:12:04Z",
            "finishedAt": "2026-11-17T09:13:41Z",
            "expiresAt": "2026-11-24T09:12:03Z",
            "fileName": "qloudpulse-k3x9d2mq7pwa-focus-2026-01_2026-10.csv.gz",
            "sizeBytes": 4818233,
            "file": "/v1/exports/0b6f3c1e-8d2a-4c57-9e11-5a7d2f4b9c30/file"
          }
        ]
      },
      "BundleReceived": {
        "type": "object",
        "required": [
          "reference",
          "outcome"
        ],
        "properties": {
          "reference": {
            "type": "string",
            "pattern": "^[0-9a-f]{20}$",
            "description": "Names this upload on the AWS accounts page and in support."
          },
          "outcome": {
            "type": "string",
            "description": "`stored`: checked and kept for replay. `encrypted`: a JWE, kept as it came; it is checked once qloudpulse decrypts it. More values may be added in /v1: treat one you do not know as taken.",
            "x-extensible-enum": [
              "stored",
              "encrypted"
            ]
          }
        },
        "description": "What an upload of an offline collection bundle answers once it is taken.",
        "examples": [
          {
            "reference": "4e1a9c07b3d25f86e0a1",
            "outcome": "stored"
          }
        ]
      },
      "EstimateRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "formatVersion",
          "tool",
          "resources",
          "notPriced"
        ],
        "properties": {
          "formatVersion": {
            "const": 1,
            "description": "Version of this format. Bump only for a change an older reader would read wrongly."
          },
          "tool": {
            "enum": [
              "pulumi",
              "terraform",
              "opentofu"
            ],
            "description": "What the change was read from: `pulumi preview --json`, or a plan as `terraform show -json` or `tofu show -json` writes it. A request read from a plan is in the plan's names and shape, as the catalogue answered a question with the same tool: each type by its Terraform name, attributes and references in snake_case, and a block as the list the plan writes. The endpoint turns it into the catalogue's own names before it prices or keeps it."
          },
          "stack": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "The project and stack, such as shop/prod, from the resources' URNs (docs/adr/0133), or, for a plan, which names no project or workspace, what the client was told the plan is of. The stacks page lists estimates by it."
          },
          "resources": {
            "type": "array",
            "maxItems": 5000,
            "description": "The resources the change creates, updates, replaces or deletes, of the catalogue's types, and those it leaves the same: every one the preview lists (with --show-sames) or the plan lists (a plan lists every resource), so that the comment can give the whole stack's cost, or at least those a changed one refers to.",
            "items": {
              "$ref": "#/components/schemas/EstimateResourceChange"
            }
          },
          "store": {
            "type": "boolean",
            "default": true,
            "description": "false (qloudpulse estimate --no-store): price the change and keep nothing, no estimate, no page, no point in the stack's history, and the answer says stored: false (docs/adr/0140). Left out or true: kept, with the names and URNs sent, unless the company keeps nothing for every run. An endpoint from before 2026-11-21 ignores it and keeps the estimate: the answer then carries estimateId and no stored, which a client that sent false must refuse."
          },
          "features": {
            "type": "array",
            "maxItems": 20,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 50
            },
            "description": "Parts of the answer the client understands. allocations: it shows a figure marked allocatedFrom apart and leaves it out of its totals; without it, such a figure is given in the reason of a not-priced answer."
          },
          "notPriced": {
            "type": "array",
            "description": "Resource types in the change of the catalogue's providers but not in its types, with how many of each.",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "type",
                "count"
              ],
              "properties": {
                "type": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200
                },
                "count": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      },
      "EstimateResourceChange": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "key",
          "change",
          "type",
          "region",
          "before",
          "after",
          "unknown"
        ],
        "properties": {
          "key": {
            "type": "string",
            "pattern": "^r[0-9a-f]{16}$",
            "description": "r + the first 16 hex digits of the SHA-256 of the resource's Pulumi URN or, from a plan, of its address in the plan, such as module.db.aws_db_instance.main[0]. The answer names the resource by it."
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 300,
            "pattern": "^[^\\u0000-\\u001f\\u007f]+$",
            "description": "What the resource is called: from a preview, the name its URN ends with, such as orders-db; from a plan, its address. Kept with the estimate and shown on its page and its stack's (docs/adr/0140). Left out by a client from before 2026-11-21, and with --no-store."
          },
          "urn": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1000,
            "pattern": "^urn:pulumi:[^\\u0000-\\u001f\\u007f]+$",
            "description": "The resource's Pulumi URN, whose SHA-256 the key starts. Kept beside the name (docs/adr/0140). Never from a plan, which has none."
          },
          "change": {
            "enum": [
              "create",
              "update",
              "replace",
              "delete",
              "same"
            ],
            "description": "same: left as it is. Answered too, with the same figure before and after and no notes, so that the client can add up what the stack costs; a changed resource that refers to it is priced with it."
          },
          "type": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "The Pulumi type token, such as aws:rds/instance:Instance, or, from a plan, the Terraform type, such as aws_db_instance."
          },
          "region": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[a-z]{2}(-[a-z]+)+-[0-9]+$",
            "description": "The AWS region, the first of: the resource's own region, its provider's, --region, the stack's aws:region, AWS_REGION, AWS_DEFAULT_REGION, and the region of the AWS profile in use on the machine the client runs on. Null when none of them names one; such a resource cannot be priced."
          },
          "before": {
            "type": [
              "object",
              "null"
            ],
            "description": "The priced attributes before the change, from the old state's inputs, and its outputs where the inputs leave one out; null for a create."
          },
          "after": {
            "type": [
              "object",
              "null"
            ],
            "description": "The priced attributes after the change; null for a delete. One neither side's inputs set comes from the old state's outputs; for a resource left the same, from its outputs where its inputs leave one out."
          },
          "unknown": {
            "type": "array",
            "uniqueItems": true,
            "items": {
              "type": "string"
            },
            "description": "Priced attributes whose value after the change is known only after apply, or is a secret. Their values are not sent. From a plan: only those the configuration sets from a value not yet known, or that the plan marks sensitive. An attribute the configuration leaves out and the provider fills in after apply is left out here too, as a preview's inputs leave it out, so that it is priced by AWS's default."
          },
          "resourceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2048,
            "description": "The cloud ID of a resource that exists before the change. Sent only with --with-resource-ids."
          },
          "references": {
            "type": "object",
            "maxProperties": 20,
            "additionalProperties": {
              "oneOf": [
                {
                  "type": "string",
                  "pattern": "^r[0-9a-f]{16}$"
                },
                {
                  "type": "array",
                  "minItems": 1,
                  "maxItems": 20,
                  "items": {
                    "type": "string",
                    "pattern": "^r[0-9a-f]{16}$"
                  }
                }
              ]
            },
            "description": "For each of the catalogue's references of this type, the key of the resource it names, such as an ECS service's task definition, or, for an attribute that is a list of resources, their keys in the order of its items, such as the capacity providers of an ECS service's capacityProviderStrategies (one key for each strategy, in the strategy's order; an endpoint from before 2026-11-19 takes single keys only)."
          }
        }
      },
      "EstimateCatalogueQuestion": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "formatVersion",
          "types"
        ],
        "description": "POST /api/report/public/estimates/catalogue: the resource types the client found in a preview or a plan, type names only. Open without a token.",
        "properties": {
          "formatVersion": {
            "const": 1
          },
          "tool": {
            "enum": [
              "pulumi",
              "terraform",
              "opentofu"
            ],
            "description": "What the types were read from; pulumi when left out. With terraform or opentofu the types are a plan's, such as aws_db_instance, and the answer is in a plan's names: each type, and its attributes and references in snake_case."
          },
          "types": {
            "type": "array",
            "maxItems": 2000,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          }
        }
      },
      "EstimateCatalogue": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "formatVersion",
          "providers",
          "types"
        ],
        "description": "The answer to a catalogueQuestion: of the types asked, those the endpoint prices and the attributes the client sends for each, the providers whose other types are counted as not priced, and the client versions. Also what --catalogue reads from a file.",
        "properties": {
          "formatVersion": {
            "const": 1
          },
          "description": {
            "type": "string"
          },
          "providers": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            },
            "description": "Pulumi packages, such as aws, whose types outside the list are counted under notPriced. For a plan, the provider's type, the last part of its address: aws for registry.terraform.io/hashicorp/aws."
          },
          "free": {
            "type": "array",
            "description": "Of the types asked, those AWS charges nothing for of their own, with why, from AWS's pricing pages. The client counts them as no cost: not sent, and not under notPriced.",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "type",
                "reason"
              ],
              "properties": {
                "type": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200
                },
                "reason": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 300
                }
              }
            }
          },
          "client": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "latest",
              "minimum",
              "download"
            ],
            "description": "The qloudpulse CLI releases this install expects. An older client than latest says a newer one is out; the endpoint refuses one below minimum.",
            "properties": {
              "latest": {
                "type": "string",
                "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
              },
              "minimum": {
                "type": "string",
                "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
              },
              "download": {
                "type": "string",
                "pattern": "^https://"
              }
            }
          },
          "types": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "type",
                "label",
                "attributes"
              ],
              "properties": {
                "type": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200
                },
                "label": {
                  "type": "string",
                  "minLength": 1,
                  "description": "What the comment calls it."
                },
                "attributes": {
                  "type": "array",
                  "uniqueItems": true,
                  "items": {
                    "type": "string",
                    "pattern": "^[^.]+(\\.[^.]+){0,3}$"
                  },
                  "description": "The paths that set its price, up to four steps: a.b takes b from the object a, or from every object in the list a."
                },
                "references": {
                  "type": "array",
                  "uniqueItems": true,
                  "items": {
                    "type": "string",
                    "pattern": "^[^.]+$"
                  },
                  "description": "Attributes whose value is another resource, sent as that resource's key under references."
                }
              }
            }
          }
        }
      },
      "EstimateResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "formatVersion",
          "currency",
          "resources"
        ],
        "properties": {
          "formatVersion": {
            "const": 1
          },
          "estimateId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "Names this estimate, so the change event sent after apply can refer to it. Only in an answer that was kept."
          },
          "stored": {
            "type": "boolean",
            "description": "Whether the endpoint kept the estimate (docs/adr/0140). false when the request said store: false or the company keeps nothing for every run: the answer then has no estimateId and no url, and nothing of the request was written. Left out by an endpoint from before 2026-11-21, which kept every estimate."
          },
          "currency": {
            "const": "USD"
          },
          "url": {
            "type": "string",
            "pattern": "^https?://",
            "description": "The estimate's page in the reports (docs/adr/0133). Only in an answer that was kept. The page names the resources from what was kept; a client from before 2026-11-21, which sent no names, added #names=<base64url of a JSON object of key to name>, which the page still reads."
          },
          "resources": {
            "type": "array",
            "description": "One answer per resource sent, those left the same included (an endpoint from before 2026-11-19 left them out).",
            "items": {
              "$ref": "#/components/schemas/EstimateResourceEstimate"
            }
          }
        }
      },
      "EstimateResourceEstimate": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "key",
          "basis"
        ],
        "properties": {
          "key": {
            "type": "string",
            "pattern": "^r[0-9a-f]{16}$"
          },
          "monthlyBefore": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0
          },
          "monthlyAfter": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0
          },
          "basis": {
            "enum": [
              "company-rate",
              "list-price",
              "not-priced"
            ],
            "description": "What the figures come from: the rate the company's bill shows it pays, AWS's list price, or nothing."
          },
          "reason": {
            "type": "string",
            "maxLength": 500,
            "description": "Why a resource is not priced, or what its figures leave out."
          },
          "notes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EstimateNote"
            }
          },
          "allocatedFrom": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "pattern": "^r[0-9a-f]{16}$"
            },
            "description": "For a share of other resources' cost, such as an ECS service's share of the Auto Scaling groups it runs on: their keys. Those resources' own figures hold the cost already, so a total leaves this one out. Sent only when the request's features include allocations."
          },
          "method": {
            "type": "string",
            "maxLength": 1000,
            "description": "For an allocated figure, how the cost was divided."
          },
          "pricedWith": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "pattern": "^r[0-9a-f]{16}$"
            },
            "description": "For a resource that costs nothing of its own, such as a task definition, launch template or capacity provider: the keys of the priced resources whose figures hold its cost."
          }
        }
      },
      "EstimateNote": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "kind",
          "text"
        ],
        "properties": {
          "kind": {
            "enum": [
              "saving",
              "usage",
              "info"
            ],
            "description": "saving: a cheaper choice from the savings catalogue. usage: what an existing resource used. info: anything else."
          },
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1000
          },
          "monthlySaving": {
            "type": "number",
            "minimum": 0
          },
          "risk": {
            "enum": [
              "low",
              "medium",
              "high"
            ],
            "description": "The recommendation type's risk (docs/adr/0116)."
          }
        }
      }
    },
    "responses": {
      "Refused": {
        "description": "The body or the query was refused; `detail` says why.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "examples": {
              "refused": {
                "summary": "Refused",
                "value": {
                  "type": "https://qloudpulse.com/api-reference.html#problem-invalid-report-query",
                  "title": "Invalid report query",
                  "status": 400,
                  "detail": "from must come before to.",
                  "instance": "/v1/reports/aws-cost-by-source"
                }
              }
            }
          }
        }
      },
      "WrongToken": {
        "description": "No API key, or one that is malformed, wrong, rotated, expired or removed. The answer does not say which.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "examples": {
              "wrongKey": {
                "summary": "Not one of your company's keys",
                "value": {
                  "type": "https://qloudpulse.com/api-reference.html#problem-not-an-api-key",
                  "title": "Not an API key",
                  "status": 401,
                  "detail": "Send one of your company's API keys as Authorization: Bearer qpk_…, as Settings, API keys showed it.",
                  "instance": "/v1/reports"
                }
              }
            }
          }
        }
      },
      "TooLarge": {
        "description": "The body is over the route's limit; `detail` says what the limit is.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "examples": {
              "tooLarge": {
                "summary": "Over the limit",
                "value": {
                  "type": "https://qloudpulse.com/api-reference.html#problem-too-large",
                  "title": "Too large",
                  "status": 413,
                  "detail": "A request is at most 1 MB. Split the stack's change, or send fewer resources.",
                  "instance": "/v1/estimates"
                }
              }
            }
          }
        }
      },
      "TooMany": {
        "description": "Past the limit for API keys: 60 requests a minute per key and 600 per company, counted in fixed minutes. `Retry-After` says how many seconds to wait, at most 60.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            },
            "examples": {
              "tooMany": {
                "summary": "Past the key's limit",
                "value": {
                  "type": "https://qloudpulse.com/api-reference.html#problem-rate-limited",
                  "title": "Too many requests",
                  "status": 429,
                  "detail": "At most 60 requests a minute per key and 600 per company. Try again in 17 s.",
                  "instance": "/v1/reports"
                }
              }
            }
          }
        },
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer",
              "examples": [
                17
              ]
            },
            "description": "Seconds to wait before the next request."
          }
        }
      }
    },
    "x-problems": {
      "not-an-api-key": {
        "type": "https://qloudpulse.com/api-reference.html#problem-not-an-api-key",
        "status": 401,
        "title": "Not an API key",
        "description": "No API key, or one that is malformed, wrong, rotated, expired or removed. Send one of your company's `qpk_` keys; an admin makes a new one under Settings, API keys."
      },
      "rate-limited": {
        "type": "https://qloudpulse.com/api-reference.html#problem-rate-limited",
        "status": 429,
        "title": "Too many requests",
        "description": "Past 60 requests a minute for the key or 600 for the company. Wait the seconds `Retry-After` says."
      },
      "not-a-source-token": {
        "type": "https://qloudpulse.com/api-reference.html#problem-not-a-source-token",
        "status": 401,
        "title": "Not an event source's token",
        "description": "No token, or one that is not one of your company's event sources or members' tokens: it may have been rotated or removed."
      },
      "too-large": {
        "type": "https://qloudpulse.com/api-reference.html#problem-too-large",
        "status": 413,
        "title": "Too large",
        "description": "The body is over the route's limit; `detail` says what the limit is."
      },
      "too-many-events": {
        "type": "https://qloudpulse.com/api-reference.html#problem-too-many-events",
        "status": 429,
        "title": "Too many events",
        "description": "Past 600 events a minute from this source. Wait a minute and send again."
      },
      "events-refused": {
        "type": "https://qloudpulse.com/api-reference.html#problem-events-refused",
        "status": 400,
        "title": "Refused: nothing was taken",
        "description": "At least one event was refused, so none was taken. `problems` gives each refused event's index and reasons; fix them and send the whole body again."
      },
      "not-a-catalogue-question": {
        "type": "https://qloudpulse.com/api-reference.html#problem-not-a-catalogue-question",
        "status": 400,
        "title": "Not a catalogue question",
        "description": "The body is not a catalogue question: `formatVersion` 1 and up to 2,000 type names."
      },
      "update-the-client": {
        "type": "https://qloudpulse.com/api-reference.html#problem-update-the-client",
        "status": 400,
        "title": "Update the client",
        "description": "The `qloudpulse` CLI that sent it is older than this install takes; `detail` says which version to get."
      },
      "not-an-estimate-request": {
        "type": "https://qloudpulse.com/api-reference.html#problem-not-an-estimate-request",
        "status": 400,
        "title": "Not an estimate request",
        "description": "The body is not an estimate request; `reasons` lists each problem."
      },
      "too-many-estimates": {
        "type": "https://qloudpulse.com/api-reference.html#problem-too-many-estimates",
        "status": 429,
        "title": "Too many estimates",
        "description": "Past 60 estimates a minute from this source. Wait a minute and send again."
      },
      "not-your-token": {
        "type": "https://qloudpulse.com/api-reference.html#problem-not-your-token",
        "status": 401,
        "title": "Not your token",
        "description": "No token, or one that is not your company's: expired, removed, or its owner left. Run `qloudpulse login` again, or make one under Your tokens."
      },
      "admins-only": {
        "type": "https://qloudpulse.com/api-reference.html#problem-admins-only",
        "status": 403,
        "title": "Admins only",
        "description": "Only your company's admins upload bundles: use an admin's own token, or an event source an admin made."
      },
      "not-taking-bundles": {
        "type": "https://qloudpulse.com/api-reference.html#problem-not-taking-bundles",
        "status": 404,
        "title": "Not taking bundles",
        "description": "Your company does not take offline collection bundles: it is not open to it, or not turned on here."
      },
      "already-delivered": {
        "type": "https://qloudpulse.com/api-reference.html#problem-already-delivered",
        "status": 409,
        "title": "Already delivered",
        "description": "This source already delivered this window. Count the bundle as delivered."
      },
      "bundle-too-large": {
        "type": "https://qloudpulse.com/api-reference.html#problem-bundle-too-large",
        "status": 413,
        "title": "Bundle too large",
        "description": "The bundle is over 64 MiB as sent. Collect fewer accounts or regions per source."
      },
      "not-a-bundle": {
        "type": "https://qloudpulse.com/api-reference.html#problem-not-a-bundle",
        "status": 415,
        "title": "Not a bundle",
        "description": "Send the bundle as `application/gzip` (a .tgz) or `application/jose` (a .jwe)."
      },
      "bundle-refused": {
        "type": "https://qloudpulse.com/api-reference.html#problem-bundle-refused",
        "status": 422,
        "title": "Bundle refused",
        "description": "A check of the bundle failed; `detail` says which and what to fix. Nothing of it was kept."
      },
      "not-handed-on": {
        "type": "https://qloudpulse.com/api-reference.html#problem-not-handed-on",
        "status": 502,
        "title": "Try again",
        "description": "The bundle could not be handed on to be checked. Send it again later."
      },
      "members-unavailable": {
        "type": "https://qloudpulse.com/api-reference.html#problem-members-unavailable",
        "status": 503,
        "title": "Try again",
        "description": "Your company's members could not be read to check the token's owner. Send the bundle again in a minute."
      },
      "not-an-export": {
        "type": "https://qloudpulse.com/api-reference.html#problem-not-an-export",
        "status": 400,
        "title": "Not an export",
        "description": "The body is not an export: `detail` says why, such as more than 13 months."
      },
      "no-such-export": {
        "type": "https://qloudpulse.com/api-reference.html#problem-no-such-export",
        "status": 404,
        "title": "No such export",
        "description": "Your company has no export with that id, or it is past its 7 days."
      },
      "export-busy": {
        "type": "https://qloudpulse.com/api-reference.html#problem-export-busy",
        "status": 409,
        "title": "An export is being built",
        "description": "Another of your company's exports is being built. Ask again once it is ready or has failed."
      },
      "export-not-ready": {
        "type": "https://qloudpulse.com/api-reference.html#problem-export-not-ready",
        "status": 409,
        "title": "Not ready",
        "description": "The export is queued, building or failed, so it has no file yet."
      },
      "invalid-report-query": {
        "type": "https://qloudpulse.com/api-reference.html#problem-invalid-report-query",
        "status": 400,
        "title": "Invalid report query",
        "description": "The query was refused, such as a window that ends before it starts or a `limit` over 10,000; `detail` says why."
      },
      "report-not-found": {
        "type": "https://qloudpulse.com/api-reference.html#problem-report-not-found",
        "status": 404,
        "title": "Report not found",
        "description": "No such report, or one your company cannot read. List them with `GET /v1/reports`."
      },
      "unsupported-report-format": {
        "type": "https://qloudpulse.com/api-reference.html#problem-unsupported-report-format",
        "status": 422,
        "title": "Unsupported report format",
        "description": "The report's definition is in a format this install cannot read yet."
      },
      "invalid-report-definition": {
        "type": "https://qloudpulse.com/api-reference.html#problem-invalid-report-definition",
        "status": 422,
        "title": "Invalid report definition",
        "description": "The report's definition has problems, so it cannot be read; `problems` lists them."
      },
      "storage-unreachable": {
        "type": "https://qloudpulse.com/api-reference.html#problem-storage-unreachable",
        "status": 503,
        "title": "Your storage cannot be reached",
        "description": "Your company keeps its data in its own AWS account, and that storage did not answer; `detail` says what to check."
      },
      "archive-busy": {
        "type": "https://qloudpulse.com/api-reference.html#problem-archive-busy",
        "status": 503,
        "title": "Report archive busy",
        "description": "The report's archive is busy. Try again in a minute."
      },
      "invalid-request": {
        "type": "https://qloudpulse.com/api-reference.html#problem-invalid-request",
        "status": 400,
        "title": "Invalid request",
        "description": "Any route: a query parameter is missing or not of its type, or the body cannot be read; `detail` says which."
      },
      "no-such-route": {
        "type": "https://qloudpulse.com/api-reference.html#problem-no-such-route",
        "status": 404,
        "title": "No such route",
        "description": "Any path under /v1 that is not a route in this contract."
      },
      "method-not-allowed": {
        "type": "https://qloudpulse.com/api-reference.html#problem-method-not-allowed",
        "status": 405,
        "title": "Method not allowed",
        "description": "Any route: it takes other methods; `detail` says which was sent."
      },
      "not-acceptable": {
        "type": "https://qloudpulse.com/api-reference.html#problem-not-acceptable",
        "status": 406,
        "title": "Not acceptable",
        "description": "Any route: it cannot answer in the media type `Accept` asks for."
      },
      "unsupported-media-type": {
        "type": "https://qloudpulse.com/api-reference.html#problem-unsupported-media-type",
        "status": 415,
        "title": "Unsupported media type",
        "description": "Any route: it does not take the body's `Content-Type`."
      }
    }
  },
  "tags": [
    {
      "name": "Events",
      "description": "Change events: releases, deploys, incidents and config changes, marked on your cost charts (docs/adr/0117). Written with an event source's token."
    },
    {
      "name": "Estimates",
      "description": "An infrastructure change priced before it is applied, which `qloudpulse estimate` sends from a pipeline (docs/adr/0123)."
    },
    {
      "name": "Reports",
      "description": "Every report your company can read, as rows, with an API key."
    },
    {
      "name": "Exports",
      "description": "Your whole bill as FOCUS 1.0, or everything qloudpulse holds about your company, built in the background and kept 7 days."
    },
    {
      "name": "Offline collection",
      "description": "Bundles from `qloudpulse-collect` for AWS accounts that qloudpulse does not reach itself (docs/adr/0141, docs/adr/0142)."
    },
    {
      "name": "API",
      "description": "The contract itself."
    }
  ],
  "externalDocs": {
    "description": "The API, for people",
    "url": "https://qloudpulse.com/api-reference.html"
  }
}
