{ "openapi": "3.1.0", "info": { "title": "Halo Developer API", "version": "1", "description": "Read datasets, charts, reports, websites and the directory with an API key, open shared reports with a link's token, and post to the directory with a source's token. Guides: https://dev.usehalo.net." }, "servers": [ { "url": "https://api.usehalo.net" } ], "tags": [ { "name": "Developer API", "description": "Read as the person who made the API key." }, { "name": "Public reports", "description": "Open one report's published version with a link's token or a signed embed token." }, { "name": "CRM", "description": "Post to a Halo CRM webhook source with its token." } ], "paths": { "/v1/developer/businesses": { "get": { "description": "Their names, places and websites. The people at a business, its email and phone, and its notes and plan are never here. Needs content.read, and a role in Halo CRM.", "operationId": "developer-list-businesses", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperPageBusinessForCode" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "apiKey": [] } ], "summary": "Businesses in the directory", "tags": [ "Developer API" ], "parameters": [ { "description": "Words to look for.", "explode": false, "in": "query", "name": "search", "schema": { "description": "Words to look for.", "maxLength": 200, "type": "string" } }, { "description": "Only this status. A listing is draft, published or archived; a business is prospect, active, paused or closed.", "explode": false, "in": "query", "name": "status", "schema": { "description": "Only this status. A listing is draft, published or archived; a business is prospect, active, paused or closed.", "maxLength": 20, "type": "string" } }, { "description": "Only this region, by its key.", "explode": false, "in": "query", "name": "region", "schema": { "description": "Only this region, by its key.", "maxLength": 60, "type": "string" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 100, "format": "int32", "maximum": 200, "minimum": 1, "type": "integer" } }, { "description": "The nextCursor of the page before.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "The nextCursor of the page before.", "maxLength": 20, "type": "string" } } ] } }, "/v1/developer/businesses/{id}": { "get": { "description": "The people at a business, its email and phone, and its notes and plan are never here. Needs content.read, and a role in Halo CRM.", "operationId": "developer-get-business", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDetailForCode" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "apiKey": [] } ], "summary": "A business and its listings", "tags": [ "Developer API" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] } }, "/v1/developer/charts": { "get": { "description": "Needs content.read.", "operationId": "developer-list-charts", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperListDeveloperChartView" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "apiKey": [] } ], "summary": "Saved charts the person can see", "tags": [ "Developer API" ], "parameters": [ { "description": "Words to match in names and descriptions.", "explode": false, "in": "query", "name": "search", "schema": { "description": "Words to match in names and descriptions.", "maxLength": 200, "type": "string" } } ] } }, "/v1/developer/charts/{id}": { "get": { "description": "Needs content.read.", "operationId": "developer-get-chart", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperChartDetailView" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "apiKey": [] } ], "summary": "A saved chart and its spec", "tags": [ "Developer API" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] } }, "/v1/developer/charts/{id}/data": { "get": { "description": "Runs the chart’s query as the person against its dataset, so seeing a chart never opens a dataset they can’t query. Needs data.query and a role that may export.", "operationId": "developer-get-chart-data", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperQueryResult" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "apiKey": [] } ], "summary": "The rows a saved chart draws", "tags": [ "Developer API" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] } }, "/v1/developer/datasets": { "get": { "description": "Needs datasets.read.", "operationId": "developer-list-datasets", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperListDeveloperDatasetView" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "apiKey": [] } ], "summary": "Datasets the person can see", "tags": [ "Developer API" ], "parameters": [ { "description": "Words to match in names and descriptions.", "explode": false, "in": "query", "name": "search", "schema": { "description": "Words to match in names and descriptions.", "maxLength": 200, "type": "string" } } ] } }, "/v1/developer/datasets/{id}": { "get": { "description": "What queries can name. Hidden fields, row policies and custom SQL are left out. Needs datasets.read.", "operationId": "developer-get-dataset", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperDatasetDetailView" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "apiKey": [] } ], "summary": "A dataset and its fields", "tags": [ "Developer API" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] } }, "/v1/developer/datasets/{id}/query": { "post": { "description": "Aggregates a dataset, or reads its rows, as the person: their access, row policies and plan limits apply. At most 1,000 rows a request; page with offset, or keyset and cursor. Rows count toward the person’s daily budget. Needs data.query and a role that may export. Closing the connection cancels the query at the source.", "operationId": "developer-query-dataset", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperQueryBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperQueryResult" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "apiKey": [] } ], "summary": "Query a dataset", "tags": [ "Developer API" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] } }, "/v1/developer/listings": { "get": { "description": "Every status the person can see, unless you ask for one: ask for published to read what’s public. The phone is the one a listing’s page gives visitors; there’s no email. Needs content.read, and a role in Halo CRM.", "operationId": "developer-list-listings", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperPageListingForCode" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "apiKey": [] } ], "summary": "Listings in the directory", "tags": [ "Developer API" ], "parameters": [ { "description": "Words to look for.", "explode": false, "in": "query", "name": "search", "schema": { "description": "Words to look for.", "maxLength": 200, "type": "string" } }, { "description": "Only this status. A listing is draft, published or archived; a business is prospect, active, paused or closed.", "explode": false, "in": "query", "name": "status", "schema": { "description": "Only this status. A listing is draft, published or archived; a business is prospect, active, paused or closed.", "maxLength": 20, "type": "string" } }, { "description": "Only this region, by its key.", "explode": false, "in": "query", "name": "region", "schema": { "description": "Only this region, by its key.", "maxLength": 60, "type": "string" } }, { "explode": false, "in": "query", "name": "limit", "schema": { "default": 100, "format": "int32", "maximum": 200, "minimum": 1, "type": "integer" } }, { "description": "The nextCursor of the page before.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "The nextCursor of the page before.", "maxLength": 20, "type": "string" } }, { "description": "Listings of one kind, by its key.", "explode": false, "in": "query", "name": "kind", "schema": { "description": "Listings of one kind, by its key.", "maxLength": 60, "type": "string" } } ] } }, "/v1/developer/listings/{id}": { "get": { "description": "The phone is the one its page gives visitors; there’s no email. Needs content.read, and a role in Halo CRM.", "operationId": "developer-get-listing", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingForCode" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "apiKey": [] } ], "summary": "A listing", "tags": [ "Developer API" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] } }, "/v1/developer/reports": { "get": { "description": "Needs content.read.", "operationId": "developer-list-reports", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperListDeveloperReportView" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "apiKey": [] } ], "summary": "Reports the person can see", "tags": [ "Developer API" ], "parameters": [ { "description": "Words to match in names and descriptions.", "explode": false, "in": "query", "name": "search", "schema": { "description": "Words to match in names and descriptions.", "maxLength": 200, "type": "string" } } ] } }, "/v1/developer/reports/{id}": { "get": { "description": "The published version unless you ask for the draft, which needs edit access. Problems: report_not_published (409). Needs content.read.", "operationId": "developer-get-report", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperReportDetailView" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "apiKey": [] } ], "summary": "A report’s document", "tags": [ "Developer API" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "The draft needs edit access.", "explode": false, "in": "query", "name": "version", "schema": { "default": "published", "description": "The draft needs edit access.", "enum": [ "published", "draft" ], "type": "string" } } ] } }, "/v1/developer/websites": { "get": { "description": "Needs content.read, and a role in Halo CMS. Refused where the plan has no Halo CMS.", "operationId": "developer-list-websites", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperListWebsiteForCode" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "apiKey": [] } ], "summary": "Websites the person can see", "tags": [ "Developer API" ], "parameters": [ { "description": "Words to match in names and descriptions.", "explode": false, "in": "query", "name": "search", "schema": { "description": "Words to match in names and descriptions.", "maxLength": 200, "type": "string" } } ] } }, "/v1/developer/websites/{id}": { "get": { "description": "Paths, titles and names: no form responses, and nothing from a draft’s content. Needs content.read.", "operationId": "developer-get-website", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteDetailForCode" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "apiKey": [] } ], "summary": "A website, its pages and collections", "tags": [ "Developer API" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] } }, "/v1/developer/whoami": { "get": { "description": "The person, their organization and role now, the key and its limits. Needs no scope, so it’s the first call to try.", "operationId": "developer-whoami", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperWhoamiView" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "apiKey": [] } ], "summary": "Who this key acts as", "tags": [ "Developer API" ] } }, "/v1/public/crm/ingest": { "post": { "description": "One object, a list, or {\"items\": [...]}, at most 2,000 items and 4 MB. Each goes through the Inbox, or applies itself if the source is trusted. Limited per address (429 rate_limited). A token that doesn’t open anything answers 401 invalid_token, as does one for an organization that’s suspended or without Halo CRM.", "operationId": "crm-ingest", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "additionalProperties": true, "description": "An item. Anything else is ignored unless the source maps it.", "properties": { "address": { "description": "Street address.", "type": "string" }, "city": { "description": "City.", "type": "string" }, "data": { "additionalProperties": true, "description": "The fields the source’s kind adds.", "type": "object" }, "description": { "description": "More about it.", "type": "string" }, "email": { "description": "Its public email.", "type": "string" }, "endsAt": { "description": "For a happening: when it ends.", "type": "string" }, "id": { "description": "Your own id for it: what tells a change from something new. Without one, the fields themselves are.", "type": "string" }, "items": { "description": "Several items, each like this one.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "lat": { "description": "Latitude.", "type": "number" }, "lng": { "description": "Longitude.", "type": "number" }, "name": { "description": "Its name.", "type": "string" }, "phone": { "description": "Its public phone number.", "type": "string" }, "postalCode": { "description": "Postal code.", "type": "string" }, "region": { "description": "A region’s key, from the directory’s settings.", "type": "string" }, "startsAt": { "description": "For a happening: when it starts, as an ISO 8601 date and time.", "type": "string" }, "summary": { "description": "A line about it.", "type": "string" }, "tags": { "description": "Tags.", "items": { "type": "string" }, "type": "array" }, "website": { "description": "Its website.", "type": "string" } }, "type": "object" }, { "description": "Several items.", "items": { "additionalProperties": true, "description": "An item. Anything else is ignored unless the source maps it.", "properties": { "address": { "description": "Street address.", "type": "string" }, "city": { "description": "City.", "type": "string" }, "data": { "additionalProperties": true, "description": "The fields the source’s kind adds.", "type": "object" }, "description": { "description": "More about it.", "type": "string" }, "email": { "description": "Its public email.", "type": "string" }, "endsAt": { "description": "For a happening: when it ends.", "type": "string" }, "id": { "description": "Your own id for it: what tells a change from something new. Without one, the fields themselves are.", "type": "string" }, "items": { "description": "Several items, each like this one.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "lat": { "description": "Latitude.", "type": "number" }, "lng": { "description": "Longitude.", "type": "number" }, "name": { "description": "Its name.", "type": "string" }, "phone": { "description": "Its public phone number.", "type": "string" }, "postalCode": { "description": "Postal code.", "type": "string" }, "region": { "description": "A region’s key, from the directory’s settings.", "type": "string" }, "startsAt": { "description": "For a happening: when it starts, as an ISO 8601 date and time.", "type": "string" }, "summary": { "description": "A line about it.", "type": "string" }, "tags": { "description": "Tags.", "items": { "type": "string" }, "type": "array" }, "website": { "description": "Its website.", "type": "string" } }, "type": "object" }, "type": "array" } ] } }, "application/octet-stream": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } } }, "description": "One item, a list of them, or {\"items\": [...]}. A source with a mapping reads its own keys instead of these.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CRMCounts" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "sourceToken": [] } ], "summary": "Post to a webhook source", "tags": [ "CRM" ] } }, "/v1/public/report": { "get": { "description": "Its published version with the saved charts it places, the organization’s brand and calendar, and what the token allows. Problems: link_not_found (404), link_expired (410, with org), report_not_published (409), invalid_token (401), rate_limited (429). Records a view (report.viewed, via public, embed or signed).", "operationId": "get-public-report", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicReportView" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "shareToken": [] } ], "summary": "The report a token opens", "tags": [ "Public reports" ], "parameters": [ { "description": "An edition’s slug, such as 2026-03, or latest (the default). An edition that isn’t there answers edition_not_found.", "explode": false, "in": "query", "name": "edition", "schema": { "description": "An edition’s slug, such as 2026-03, or latest (the default). An edition that isn’t there answers edition_not_found.", "maxLength": 64, "type": "string" } }, { "description": "The host of the page that sent the reader, when another site did. Counted in the report’s Views.", "explode": false, "in": "query", "name": "ref", "schema": { "description": "The host of the page that sent the reader, when another site did. Counted in the report’s Views.", "maxLength": 253, "type": "string" } }, { "description": "The page the reader opens on, when the link names one. Counted in the report’s Views.", "explode": false, "in": "query", "name": "page", "schema": { "description": "The page the reader opens on, when the link names one. Counted in the report’s Views.", "maxLength": 40, "type": "string" } }, { "description": "Set by Cloudflare: the reader’s country, counted in the report’s Views.", "in": "header", "name": "CF-IPCountry", "schema": { "description": "Set by Cloudflare: the reader’s country, counted in the report’s Views.", "type": "string" } }, { "description": "Tells phones, tablets and desktops apart in the report’s Views, and robots, which aren’t counted.", "in": "header", "name": "User-Agent", "schema": { "description": "Tells phones, tablets and desktops apart in the report’s Views, and robots, which aren’t counted.", "type": "string" } } ] } }, "/v1/public/report/editions": { "get": { "description": "What a link can read of the report’s editions, newest period first. Withdrawn editions are left out.", "operationId": "list-public-report-editions", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicEditionsView" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "shareToken": [] } ], "summary": "A report’s editions", "tags": [ "Public reports" ] } }, "/v1/public/report/export": { "post": { "description": "Writes the whole result of a query the report could make (as POST /v1/public/report/query checks it) to a CSV, Excel or JSON file, up to 10,000 rows (422 export_too_large past that). Only where the report’s author allows exports (sharing.allowExport; 403 downloads_off otherwise). Rows come from the snapshot answer named, when the token reads it, else from the source, with the link’s row policies and locked filters. 10 an hour for one client and link (429 rate_limited). Audited as dataset.exported.", "operationId": "export-public-report-rows", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicExportInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "contentEncoding": "base64", "type": "string" } } }, "description": "OK", "headers": { "Content-Disposition": { "schema": { "type": "string" } }, "Content-Type": { "schema": { "type": "string" } }, "X-Halo-Rows": { "schema": { "description": "How many rows the file holds.", "format": "int64", "type": "integer" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "shareToken": [] } ], "summary": "Download an element’s rows from a link", "tags": [ "Public reports" ], "parameters": [ { "description": "The edition the rows are from, as when querying.", "explode": false, "in": "query", "name": "edition", "schema": { "description": "The edition the rows are from, as when querying.", "maxLength": 64, "type": "string" } } ] } }, "/v1/public/report/frame": { "get": { "description": "The CSP frame-ancestors sources for the token: 'none' for public links, the report’s embed sites for embed links and signed embeds. They’re set as a header before serving /embed/{token}; for /embed/signed, whose token it never sees, the viewer asks and refuses parents that aren’t allowed.", "operationId": "get-public-report-frame", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicFrameView" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "shareToken": [] } ], "summary": "Who may frame the report", "tags": [ "Public reports" ] } }, "/v1/public/report/goals": { "post": { "description": "Goals a goal scorecard of the published report shows (HAU-1907), and how each stands, as the token’s reader: nobody’s row policies for links, the signed attributes for signed embeds. A request no scorecard makes is 403 shared_field. A report locked to some rows shows its goals' names without figures. An edition’s link shows only its published figures (figures_only).", "operationId": "get-public-report-goals", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoalScorecardBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoalScorecardView" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "shareToken": [] } ], "summary": "The goals a scorecard of the report shows", "tags": [ "Public reports" ], "parameters": [ { "description": "The edition asked about.", "explode": false, "in": "query", "name": "edition", "schema": { "description": "The edition asked about.", "maxLength": 64, "type": "string" } } ] } }, "/v1/public/report/images/{id}": { "get": { "description": "The addresses of a picture the published report places. Images it doesn’t place are 404.", "operationId": "get-public-report-image", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportImageView" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "shareToken": [] } ], "summary": "An image the report places", "tags": [ "Public reports" ], "parameters": [ { "description": "The edition whose document draws the map.", "explode": false, "in": "query", "name": "edition", "schema": { "description": "The edition whose document draws the map.", "maxLength": 64, "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] } }, "/v1/public/report/pdf": { "post": { "description": "Prints the report as the link shows it, as nobody, where its author allows PDFs (sharing.allowPdf; 403 downloads_off otherwise, and always for signed embeds). One file serves every reader of the same snapshot, edition or hour: when it’s made already the answer has its url; otherwise it has the job’s id, to ask after with GET /v1/public/report/pdf/{id}. 10 an hour for one client and link (429 rate_limited); 503 pdf_unavailable when the server has no renderer.", "operationId": "start-public-report-pdf", "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPDFView" } } }, "description": "Accepted" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "shareToken": [] } ], "summary": "Download the report as a PDF from a link", "tags": [ "Public reports" ], "parameters": [ { "description": "An edition’s slug, such as 2026-03, or latest (the default). An edition that isn’t there answers edition_not_found.", "explode": false, "in": "query", "name": "edition", "schema": { "description": "An edition’s slug, such as 2026-03, or latest (the default). An edition that isn’t there answers edition_not_found.", "maxLength": 64, "type": "string" } } ] } }, "/v1/public/report/pdf/{id}": { "get": { "description": "The job’s status, and the file’s url once it’s ready, for the next hour. A job of another report isn’t found.", "operationId": "get-public-report-pdf", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPDFView" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "shareToken": [] } ], "summary": "Where a reader’s PDF stands", "tags": [ "Public reports" ], "parameters": [ { "explode": false, "in": "query", "name": "edition", "schema": { "maxLength": 64, "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] } }, "/v1/public/report/preview": { "get": { "description": "The words for a link’s preview on another site, which the edge Worker gives to crawlers. Unlike GET /v1/public/report, it records no view. A revoked or expired link, or a report in the Trash, answers as GET /v1/public/report does, so nothing of the report shows.", "operationId": "get-public-report-preview", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPreviewView" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "shareToken": [] } ], "summary": "What a link shows when it’s shared", "tags": [ "Public reports" ], "parameters": [ { "description": "An edition’s slug, such as 2026-03, or latest (the default). An edition that isn’t there answers edition_not_found.", "explode": false, "in": "query", "name": "edition", "schema": { "description": "An edition’s slug, such as 2026-03, or latest (the default). An edition that isn’t there answers edition_not_found.", "maxLength": 64, "type": "string" } } ] } }, "/v1/public/report/preview/image": { "get": { "description": "1200 by 630, taken from the report’s snapshot when it was published, so it shows what anyone opening the link sees.", "operationId": "get-public-report-preview-image", "responses": { "200": { "content": { "application/json": { "schema": { "contentEncoding": "base64", "type": "string" } } }, "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" } }, "Content-Type": { "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "shareToken": [] } ], "summary": "The picture a link shows when it’s shared", "tags": [ "Public reports" ], "parameters": [ { "description": "An edition’s slug, such as 2026-03, or latest (the default). An edition that isn’t there answers edition_not_found.", "explode": false, "in": "query", "name": "edition", "schema": { "description": "An edition’s slug, such as 2026-03, or latest (the default). An edition that isn’t there answers edition_not_found.", "maxLength": 64, "type": "string" } } ] } }, "/v1/public/report/query": { "post": { "description": "Runs a query the published report could make itself: its dataset is one the report uses, and every field it names one the report shows, filters, swaps or drills to (403 shared_field otherwise). A signed embed’s locked filters are added, and row policies see the token’s reader: nobody for links, the signed attributes for signed embeds. Answers as POST /v1/orgs/{org}/datasets/{id}/query does.", "operationId": "query-public-report", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicQueryInputBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResultView" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "shareToken": [] } ], "summary": "Query a dataset the report shows", "tags": [ "Public reports" ], "parameters": [ { "description": "The edition asked about: its document decides what may be asked, and its period what dates mean.", "explode": false, "in": "query", "name": "edition", "schema": { "description": "The edition asked about: its document decides what may be asked, and its period what dates mean.", "maxLength": 64, "type": "string" } } ] } }, "/v1/public/report/regions/{id}": { "get": { "description": "Shapes come with their TopoJSON; ZIP code groups with their ZIP codes, whose shapes load from the public geo files. Sets the report’s maps don’t draw are 404.", "operationId": "get-public-report-region-set", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicRegionSetView" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "shareToken": [] } ], "summary": "A custom region set the report’s maps draw", "tags": [ "Public reports" ], "parameters": [ { "description": "The edition whose document draws the map.", "explode": false, "in": "query", "name": "edition", "schema": { "description": "The edition whose document draws the map.", "maxLength": 64, "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] } }, "/v1/public/report/snapshots/{id}/answers/{key}": { "get": { "description": "The query result the snapshot stored for the question whose key it is (GET /v1/public/report’s snapshot.answers). Only public and embed links read snapshots, and only their own report’s; anything else is 404 snapshot_not_found, as is a key the snapshot doesn’t hold: ask that question live. The edge Worker caches these per snapshot.", "operationId": "get-public-report-snapshot-answer", "responses": { "200": { "content": { "application/json": { "schema": { "contentEncoding": "base64", "type": "string" } } }, "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" } }, "Content-Type": { "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "shareToken": [] } ], "summary": "An answer from the report’s snapshot", "tags": [ "Public reports" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "An answer’s key, or a region set’s id.", "in": "path", "name": "key", "required": true, "schema": { "description": "An answer’s key, or a region set’s id.", "pattern": "^[0-9a-f]{64}$|^[0-9a-f-]{36}$", "type": "string" } } ] } }, "/v1/public/report/snapshots/{id}/regions/{key}": { "get": { "description": "A custom region set the snapshot’s maps drew, as GET /v1/public/report/regions/{id} answers it, by its id (snapshot.regions).", "operationId": "get-public-report-snapshot-region-set", "responses": { "200": { "content": { "application/json": { "schema": { "contentEncoding": "base64", "type": "string" } } }, "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" } }, "Content-Type": { "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "shareToken": [] } ], "summary": "A region set from the report’s snapshot", "tags": [ "Public reports" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "An answer’s key, or a region set’s id.", "in": "path", "name": "key", "required": true, "schema": { "description": "An answer’s key, or a region set’s id.", "pattern": "^[0-9a-f]{64}$|^[0-9a-f-]{36}$", "type": "string" } } ] } }, "/v1/public/report/snapshots/{id}/thumbnail": { "get": { "description": "The picture its snapshot took of the first page, as listed in GET /v1/public/report/editions.", "operationId": "get-public-report-snapshot-thumbnail", "responses": { "200": { "content": { "application/json": { "schema": { "contentEncoding": "base64", "type": "string" } } }, "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" } }, "Content-Type": { "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error" } }, "security": [ { "shareToken": [] } ], "summary": "An edition’s first-page picture", "tags": [ "Public reports" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] } } }, "components": { "schemas": { "PublicRegionSetView": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "kind": { "enum": [ "shapes", "zip_codes" ], "type": "string" }, "name": { "type": "string" }, "regions": { "description": "ZIP code groups: each region’s ZIP codes. Their shapes come from the public geo files.", "items": { "$ref": "#/components/schemas/ZipGroupView" }, "type": [ "array", "null" ] }, "topology": { "description": "Shapes: TopoJSON with one object, regions, whose geometries have a name property." }, "version": { "format": "int32", "type": "integer" } }, "required": [ "id", "name", "version", "kind" ], "type": "object" }, "ZipGroupView": { "additionalProperties": false, "properties": { "name": { "type": "string" }, "zips": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "name", "zips" ], "type": "object" }, "QueryResultView": { "additionalProperties": false, "properties": { "columns": { "items": { "$ref": "#/components/schemas/Column" }, "type": [ "array", "null" ] }, "goals": { "description": "The goals the request compared with, in its order: the measure each is compared with, or why it isn’t (HAU-1906). Their values are the columns with role goal.", "items": { "$ref": "#/components/schemas/GoalComparison" }, "type": [ "array", "null" ] }, "policies": { "description": "Ids of the dataset’s row policies that filtered the rows; left out when none did.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "rows": { "items": { "items": {}, "type": [ "array", "null" ] }, "type": [ "array", "null" ] }, "sql": { "description": "The SQL that ran, for members who can write custom SQL.", "type": "string" }, "stats": { "$ref": "#/components/schemas/QueryStats" }, "totals": { "additionalProperties": {}, "description": "The measures over every row the query returns, by column key. Set when the request asked for totals.", "type": "object" }, "warnings": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "columns", "rows", "stats", "warnings" ], "type": "object" }, "QueryStats": { "additionalProperties": false, "properties": { "cached": { "description": "The result came from the result cache, not from running the query at the source.", "type": "boolean" }, "computedAt": { "description": "When the source answered. Older than the request when the result is cached.", "format": "date-time", "type": "string" }, "durationMs": { "description": "How long this request took to answer, from the cache or the source.", "format": "int64", "type": "integer" }, "extractRefreshedAt": { "description": "Set when the dataset’s extract answered instead of the source: when the extract was last refreshed.", "format": "date-time", "type": "string" }, "hasMore": { "description": "More rows exist past the limit.", "type": "boolean" }, "nextCursor": { "description": "For keyset requests with more rows: pass it as the next window’s cursor.", "type": "string" }, "rowCount": { "format": "int64", "type": "integer" }, "timeZone": { "description": "Timestamps in rows are wall-clock times in this zone.", "type": "string" }, "total": { "description": "Every row the query returns, ignoring limit and offset. Set when the request asked for count.", "format": "int64", "type": "integer" }, "totalEstimated": { "description": "total is the source’s estimate: the result is too big to count cheaply.", "type": "boolean" }, "version": { "description": "The dataset version that answered.", "format": "int32", "type": "integer" } }, "required": [ "durationMs", "rowCount", "hasMore", "timeZone", "version", "cached", "computedAt" ], "type": "object" }, "GoalComparison": { "additionalProperties": false, "properties": { "direction": { "enum": [ "higher", "lower" ], "type": "string" }, "id": { "type": "string" }, "measure": { "description": "The key of the measure column it’s compared with.", "type": "string" }, "name": { "type": "string" }, "note": { "description": "Why the goal isn’t compared here, such as a chart filtered to part of what the goal covers. Its columns are left out.", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "Column": { "additionalProperties": false, "properties": { "aggregate": { "type": "string" }, "binWidth": { "format": "double", "type": "number" }, "compares": { "description": "On goal columns: the key of the measure column compared.", "type": "string" }, "field": { "type": "string" }, "format": { "type": "string" }, "goal": { "description": "On goal columns: the goal’s id.", "type": "string" }, "grain": { "type": "string" }, "key": { "type": "string" }, "label": { "type": "string" }, "part": { "description": "On goal columns: the goal’s value, the difference from it, the share of it reached (1 is the goal), or on_track, at_risk or behind.", "enum": [ "goal", "difference", "percent", "status" ], "type": "string" }, "role": { "enum": [ "dimension", "measure", "goal" ], "type": "string" }, "semanticType": { "type": "string" }, "type": { "type": "string" } }, "required": [ "key", "field", "label", "role", "type" ], "type": "object" }, "PublicQueryInputBody": { "additionalProperties": false, "properties": { "datasetId": { "description": "The dataset to query; the request’s own datasetId is ignored.", "type": "string" }, "request": { "$ref": "#/components/schemas/QueryRequest" } }, "required": [ "datasetId", "request" ], "type": "object" }, "QueryRequest": { "additionalProperties": false, "properties": { "countRows": { "type": "boolean" }, "cursor": { "type": "string" }, "datasetId": { "type": "string" }, "datasetVersion": { "format": "int64", "type": "integer" }, "dimensions": { "items": { "$ref": "#/components/schemas/Dimension" }, "type": [ "array", "null" ] }, "filters": { "items": { "$ref": "#/components/schemas/Filter" }, "type": [ "array", "null" ] }, "goals": { "items": { "$ref": "#/components/schemas/QueryGoal" }, "type": [ "array", "null" ] }, "groupRows": { "items": { "$ref": "#/components/schemas/Dimension" }, "type": [ "array", "null" ] }, "keyset": { "type": "boolean" }, "limit": { "format": "int64", "type": "integer" }, "measures": { "items": { "$ref": "#/components/schemas/Measure" }, "type": [ "array", "null" ] }, "offset": { "format": "int64", "type": "integer" }, "parameters": { "additionalProperties": {}, "type": "object" }, "pivot": { "$ref": "#/components/schemas/QueryRequestPivot" }, "sorts": { "items": { "$ref": "#/components/schemas/Sort" }, "type": [ "array", "null" ] }, "specVersion": { "format": "double", "type": "number" }, "timeZone": { "type": "string" }, "totals": { "type": "boolean" } }, "required": [ "datasetId", "specVersion" ], "type": "object" }, "Sort": { "additionalProperties": false, "properties": { "direction": { "type": "string" }, "field": { "type": "string" } }, "required": [ "direction", "field" ], "type": "object" }, "QueryRequestPivot": { "additionalProperties": false, "properties": { "dimension": { "$ref": "#/components/schemas/Dimension" }, "values": { "items": {}, "type": [ "array", "null" ] } }, "required": [ "dimension", "values" ], "type": "object" }, "Dimension": { "additionalProperties": false, "properties": { "alias": { "type": "string" }, "binWidth": { "format": "double", "type": "number" }, "field": { "type": "string" }, "grain": { "type": "string" } }, "required": [ "field" ], "type": "object" }, "Measure": { "additionalProperties": false, "properties": { "aggregate": { "type": "string" }, "alias": { "type": "string" }, "field": { "type": "string" } }, "required": [ "field" ], "type": "object" }, "QueryGoal": { "additionalProperties": false, "properties": { "goalId": { "type": "string" } }, "required": [ "goalId" ], "type": "object" }, "Filter": { "additionalProperties": false, "properties": { "field": { "type": "string" }, "op": { "type": "string" }, "range": { "$ref": "#/components/schemas/DateRange" }, "values": { "items": {}, "type": [ "array", "null" ] } }, "required": [ "field", "op" ], "type": "object" }, "DateRange": { "additionalProperties": false, "properties": { "end": { "type": "string" }, "kind": { "type": "string" }, "n": { "format": "int64", "type": "integer" }, "preset": { "type": "string" }, "start": { "type": "string" } }, "required": [ "kind" ], "type": "object" }, "PublicPreviewView": { "additionalProperties": false, "properties": { "description": { "type": "string" }, "hasImage": { "description": "Whether GET /v1/public/report/preview/image has a picture: only a report on snapshots has one, built when it’s published.", "type": "boolean" }, "siteName": { "description": "The organization’s name.", "type": "string" }, "title": { "description": "The report’s title, after the edition’s label when the link opens one.", "type": "string" } }, "required": [ "title", "description", "siteName", "hasImage" ], "type": "object" }, "PublicPDFView": { "additionalProperties": false, "properties": { "error": { "type": "string" }, "filename": { "type": "string" }, "id": { "description": "The job making it, to ask after with GET /v1/public/report/pdf/{id}. Left out when the file was ready already.", "type": "string" }, "status": { "enum": [ "queued", "running", "succeeded", "failed", "canceled" ], "type": "string" }, "url": { "description": "Downloads the PDF for the next hour, once it’s ready.", "type": "string" } }, "required": [ "status" ], "type": "object" }, "ReportImageView": { "additionalProperties": false, "properties": { "alt": { "type": "string" }, "image": { "$ref": "#/components/schemas/ImageView", "description": "Once ready." }, "name": { "type": "string" } }, "required": [ "name", "alt" ], "type": "object" }, "ImageView": { "additionalProperties": false, "properties": { "alt": { "type": "string" }, "animated": { "type": "boolean" }, "crop": { "$ref": "#/components/schemas/CropView" }, "dominantColor": { "description": "#rrggbb; absent when the image has no opaque pixels.", "type": "string" }, "focalPoint": { "$ref": "#/components/schemas/PointView" }, "format": { "description": "The type uploaded, by its contents.", "enum": [ "png", "jpeg", "webp", "avif", "gif", "svg", "heic" ], "type": "string" }, "height": { "format": "int64", "type": "integer" }, "id": { "type": "string" }, "placeholder": { "description": "A tiny blurred WebP as a data: URI.", "type": "string" }, "url": { "description": "The full-size file in a type every client reads: SVG, GIF for animations, PNG or JPEG.", "type": "string" }, "variants": { "description": "WebP (and AVIF for still images) by width, for srcset.", "items": { "$ref": "#/components/schemas/ImageVariantView" }, "type": [ "array", "null" ] }, "width": { "description": "Pixels, after the EXIF orientation.", "format": "int64", "type": "integer" } }, "required": [ "id", "width", "height", "format", "animated", "alt", "url", "variants" ], "type": "object" }, "ImageVariantView": { "additionalProperties": false, "properties": { "bytes": { "format": "int64", "type": "integer" }, "format": { "enum": [ "webp", "avif" ], "type": "string" }, "height": { "format": "int64", "type": "integer" }, "url": { "type": "string" }, "width": { "format": "int64", "type": "integer" } }, "required": [ "url", "format", "width", "height", "bytes" ], "type": "object" }, "PointView": { "additionalProperties": false, "properties": { "x": { "description": "Across, as a fraction of the image’s width.", "format": "double", "maximum": 1, "minimum": 0, "type": "number" }, "y": { "description": "Down, as a fraction of the image’s height.", "format": "double", "maximum": 1, "minimum": 0, "type": "number" } }, "required": [ "x", "y" ], "type": "object" }, "CropView": { "additionalProperties": false, "properties": { "height": { "format": "double", "maximum": 1, "minimum": 0.01, "type": "number" }, "width": { "format": "double", "maximum": 1, "minimum": 0.01, "type": "number" }, "x": { "description": "Left edge, as a fraction of the image’s width.", "format": "double", "maximum": 1, "minimum": 0, "type": "number" }, "y": { "description": "Top edge, as a fraction of the image’s height.", "format": "double", "maximum": 1, "minimum": 0, "type": "number" } }, "required": [ "x", "y", "width", "height" ], "type": "object" }, "GoalScorecardView": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/GoalCardView" }, "type": [ "array", "null" ] } }, "required": [ "items" ], "type": "object" }, "GoalCardView": { "additionalProperties": false, "properties": { "actual": { "format": "double", "type": [ "number", "null" ] }, "asOf": { "format": "date-time", "type": [ "string", "null" ] }, "datasetId": { "type": "string" }, "difference": { "format": "double", "type": [ "number", "null" ] }, "format": { "type": "string" }, "goal": { "format": "double", "type": [ "number", "null" ] }, "id": { "type": "string" }, "missing": { "description": "A goal the scorecard names that’s deleted or that this reader can’t open.", "type": "boolean" }, "name": { "description": "Empty for a goal that’s missing.", "type": "string" }, "percentOfGoal": { "description": "100 at the goal.", "format": "double", "type": [ "number", "null" ] }, "periodEnd": { "type": [ "string", "null" ] }, "periodStart": { "description": "What’s compared, to date. Null with no grain: all time.", "type": [ "string", "null" ] }, "points": { "items": { "$ref": "#/components/schemas/GoalPointView" }, "type": [ "array", "null" ] }, "status": { "description": "Empty when there’s nothing to compare.", "enum": [ "on_track", "at_risk", "behind", "" ], "type": "string" }, "unavailable": { "description": "Why there’s no comparison: a broken goal, one a row policy hides, or no value for this period.", "type": "string" } }, "required": [ "id", "name", "periodStart", "periodEnd", "actual", "goal", "difference", "percentOfGoal", "status", "format", "points", "asOf" ], "type": "object" }, "GoalPointView": { "additionalProperties": false, "properties": { "actual": { "format": "double", "type": [ "number", "null" ] }, "goal": { "format": "double", "type": [ "number", "null" ] }, "period": { "type": "string" } }, "required": [ "period", "actual", "goal" ], "type": "object" }, "GoalScorecardBody": { "additionalProperties": false, "properties": { "datasetId": { "description": "Every goal on this dataset, by name, when goalIds is empty.", "type": "string" }, "goalIds": { "description": "The goals, in this order.", "items": { "type": "string" }, "maxItems": 20, "type": [ "array", "null" ] } }, "type": "object" }, "PublicFrameView": { "additionalProperties": false, "properties": { "frameAncestors": { "description": "CSP frame-ancestors sources: 'none' for public links, the report’s embed sites for embeds.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "frameAncestors" ], "type": "object" }, "PublicExportInputBody": { "additionalProperties": false, "properties": { "columns": { "description": "Result column keys to write, in order. Defaults to every column.", "items": { "type": "string" }, "maxItems": 500, "type": [ "array", "null" ] }, "datasetId": { "description": "The dataset to query; the request’s own datasetId is ignored.", "type": "string" }, "format": { "enum": [ "csv", "xlsx", "json" ], "type": "string" }, "name": { "description": "The file’s name, without the extension. Defaults to the report’s title.", "maxLength": 200, "type": "string" }, "request": { "$ref": "#/components/schemas/QueryRequest", "description": "A query the report could make, as POST /v1/public/report/query takes it. Its offset is ignored. Its limit caps the rows, as a top-ten chart’s does: send 1000000 for every row (the default is 1,000)." }, "snapshot": { "$ref": "#/components/schemas/SnapshotStruct", "description": "The snapshot answer the reader drew the element from, when it came from one: the rows are read from it rather than the source." } }, "required": [ "datasetId", "request", "format" ], "type": "object" }, "SnapshotStruct": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "key": { "maxLength": 128, "type": "string" } }, "required": [ "id", "key" ], "type": "object" }, "PublicEditionsView": { "additionalProperties": false, "properties": { "items": { "description": "Newest period first. Withdrawn editions are left out.", "items": { "$ref": "#/components/schemas/PublicEditionListingView" }, "type": [ "array", "null" ] } }, "required": [ "items" ], "type": "object" }, "PublicEditionListingView": { "additionalProperties": false, "properties": { "correctedAt": { "format": "date-time", "type": "string" }, "label": { "type": "string" }, "periodEnd": { "format": "date", "type": "string" }, "periodStart": { "format": "date", "type": "string" }, "publishedAt": { "format": "date-time", "type": "string" }, "slug": { "type": "string" }, "thumbnailUrl": { "description": "Its first-page picture, read with the same token.", "type": "string" } }, "required": [ "slug", "label", "periodStart", "periodEnd", "publishedAt" ], "type": "object" }, "PublicReportView": { "additionalProperties": false, "properties": { "charts": { "additionalProperties": {}, "description": "The saved charts the document places, by chartId: Visualization specs as they are now.", "type": "object" }, "datasets": { "additionalProperties": { "$ref": "#/components/schemas/PublicDatasetView" }, "description": "The datasets the document and its saved charts query, by id, so filters, controls and cross-filters know which they reach.", "type": "object" }, "document": { "description": "The published version, a Report document (https://schemas.usehalo.net/spec/v1/report.json), upgraded to the current spec." }, "edition": { "$ref": "#/components/schemas/PublicEditionView", "description": "The edition this is: its document, snapshot and version are the edition’s." }, "editions": { "$ref": "#/components/schemas/PublicEditionsSummaryView", "description": "On a report with editions: which is the latest, and how many there are." }, "env": { "$ref": "#/components/schemas/PublicEnvView" }, "link": { "$ref": "#/components/schemas/PublicLinkView" }, "organization": { "$ref": "#/components/schemas/PublicOrgView" }, "report": { "$ref": "#/components/schemas/PublicReportInfoView" }, "sharing": { "$ref": "#/components/schemas/PublicSharingView" }, "snapshot": { "$ref": "#/components/schemas/PublicSnapshotView", "description": "Public and embed links of a report on snapshots, once one is built: read its answers from GET /v1/public/report/snapshots/{id}/answers/{key}; ask anything else live." } }, "required": [ "report", "document", "charts", "datasets", "organization", "env", "sharing", "link" ], "type": "object" }, "PublicSnapshotView": { "additionalProperties": false, "properties": { "answers": { "description": "The questions it answers, by key: the SHA-256, in hex, of the canonical JSON of [datasetId, request].", "items": { "type": "string" }, "type": [ "array", "null" ] }, "builtAt": { "description": "When its answers were computed.", "format": "date-time", "type": "string" }, "id": { "type": "string" }, "regions": { "description": "The custom region sets it holds, by id.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "id", "builtAt", "answers", "regions" ], "type": "object" }, "PublicSharingView": { "additionalProperties": false, "properties": { "allowExport": { "description": "Readers may export chart and table rows (POST /v1/public/report/export) and download chart images (PNG).", "type": "boolean" }, "allowPdf": { "description": "Readers of public links and embeds may download the report as a PDF (POST /v1/public/report/pdf).", "type": "boolean" } }, "required": [ "allowExport", "allowPdf" ], "type": "object" }, "PublicReportInfoView": { "additionalProperties": false, "properties": { "description": { "type": "string" }, "id": { "type": "string" }, "publishedAt": { "format": "date-time", "type": "string" }, "title": { "description": "The published version’s title.", "type": "string" }, "version": { "description": "The published version’s number.", "format": "int32", "type": "integer" } }, "required": [ "id", "title", "description", "publishedAt", "version" ], "type": "object" }, "PublicOrgView": { "additionalProperties": false, "properties": { "faviconUrl": { "description": "Organizations don’t set one yet.", "type": "string" }, "logoUrl": { "type": "string" }, "name": { "type": "string" }, "showBadge": { "description": "Show Powered by Halo: unless the plan removes it.", "type": "boolean" }, "slug": { "type": "string" }, "theme": { "$ref": "#/components/schemas/Theme", "description": "The organization’s brand theme; null means Halo’s." } }, "required": [ "name", "slug", "theme", "showBadge" ], "type": "object" }, "Theme": { "additionalProperties": false, "properties": { "bodyFont": { "$ref": "#/components/schemas/ThemeFont" }, "dark": { "$ref": "#/components/schemas/ThemeMode" }, "headingFont": { "$ref": "#/components/schemas/ThemeFont" }, "light": { "$ref": "#/components/schemas/ThemeMode" }, "name": { "type": "string" }, "radius": { "type": "string" }, "specVersion": { "format": "double", "type": "number" } }, "required": [ "light", "name", "specVersion" ], "type": "object" }, "ThemeMode": { "additionalProperties": false, "properties": { "accent": { "type": "string" }, "palette": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "surface": { "type": "string" }, "text": { "type": "string" }, "textMuted": { "type": "string" } }, "required": [ "accent", "palette", "surface", "text", "textMuted" ], "type": "object" }, "ThemeFont": { "additionalProperties": false, "properties": { "family": { "type": "string" }, "kitId": { "type": "string" }, "source": { "type": "string" } }, "required": [ "family", "source" ], "type": "object" }, "PublicLinkView": { "additionalProperties": false, "properties": { "element": { "description": "Signed embeds of one element: its id.", "type": "string" }, "expiresAt": { "format": "date-time", "type": "string" }, "kind": { "description": "render: the PDF renderer’s short-lived token for one published version.", "enum": [ "public", "embed", "signed", "render" ], "type": "string" }, "lockedFilters": { "description": "A signed embed’s locked filters, or a render token’s reader filters, added to every query; show them as fixed.", "items": { "$ref": "#/components/schemas/Filter" }, "type": [ "array", "null" ] } }, "required": [ "kind", "lockedFilters" ], "type": "object" }, "PublicEnvView": { "additionalProperties": false, "properties": { "anchor": { "description": "The date this report reads as of, when it isn’t today: relative dates resolve as if today were this date and that day were complete.", "format": "date", "type": "string" }, "fiscalStartMonth": { "format": "int64", "maximum": 12, "minimum": 1, "type": "integer" }, "period": { "$ref": "#/components/schemas/PublicPeriodView", "description": "The whole period an anchored report covers: a chart over exactly this range compares with the previous whole period." }, "timeZone": { "description": "The organization’s; a report’s own timeZone wins over it.", "type": "string" }, "weekStartsOn": { "description": "0 Sunday, 1 Monday.", "format": "int64", "type": "integer" } }, "required": [ "timeZone", "weekStartsOn", "fiscalStartMonth" ], "type": "object" }, "PublicPeriodView": { "additionalProperties": false, "properties": { "end": { "format": "date", "type": "string" }, "start": { "format": "date", "type": "string" } }, "required": [ "start", "end" ], "type": "object" }, "PublicEditionsSummaryView": { "additionalProperties": false, "properties": { "count": { "format": "int64", "type": "integer" }, "latest": { "description": "The slug links open by default. Empty when what’s published now is no edition.", "type": "string" }, "latestLabel": { "type": "string" } }, "required": [ "latest", "latestLabel", "count" ], "type": "object" }, "PublicEditionView": { "additionalProperties": false, "properties": { "anchor": { "description": "The date the edition reads as of.", "format": "date", "type": "string" }, "correctedAt": { "format": "date-time", "type": "string" }, "correctionNote": { "type": "string" }, "label": { "description": "What it’s called, as in March 2026.", "type": "string" }, "liveFilters": { "description": "false: readers see only the published figures, and queries answer edition_figures_only. Signed embeds are always live.", "type": "boolean" }, "periodEnd": { "format": "date", "type": "string" }, "periodStart": { "format": "date", "type": "string" }, "publishedAt": { "format": "date-time", "type": "string" }, "slug": { "type": "string" } }, "required": [ "slug", "label", "periodStart", "periodEnd", "anchor", "publishedAt", "liveFilters" ], "type": "object" }, "PublicDatasetView": { "additionalProperties": false, "properties": { "defaultDateField": { "type": "string" }, "fields": { "description": "The fields the report’s queries may name, in the dataset’s order; no others.", "items": { "$ref": "#/components/schemas/PublicFieldView" }, "type": [ "array", "null" ] } }, "required": [ "fields" ], "type": "object" }, "PublicFieldView": { "additionalProperties": false, "properties": { "label": { "type": "string" }, "name": { "type": "string" }, "role": { "enum": [ "dimension", "measure" ], "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "label", "type", "role" ], "type": "object" }, "CRMCounts": { "additionalProperties": false, "properties": { "applied": { "format": "int64", "type": "integer" }, "dropped": { "format": "int64", "type": "integer" }, "found": { "format": "int64", "type": "integer" }, "jobId": { "description": "That job, when there is one.", "type": "string" }, "new": { "format": "int64", "type": "integer" }, "queued": { "description": "Rows left to a background job, for a large file. Its notification says how it went.", "format": "int64", "type": "integer" }, "skipped": { "additionalProperties": { "format": "int64", "type": "integer" }, "description": "Values that couldn’t be used, by field: a date nobody can read, a region you don’t have. The rest of each item still arrived.", "type": "object" }, "unchanged": { "format": "int64", "type": "integer" }, "updated": { "format": "int64", "type": "integer" } }, "required": [ "found", "new", "updated", "unchanged", "applied", "dropped" ], "type": "object" }, "DeveloperWhoamiView": { "additionalProperties": false, "properties": { "key": { "$ref": "#/components/schemas/DeveloperKey" }, "limits": { "$ref": "#/components/schemas/DeveloperLimits" }, "organization": { "$ref": "#/components/schemas/DeveloperOrganization" }, "role": { "description": "Their role now. What the key may do follows it.", "type": "string" }, "user": { "$ref": "#/components/schemas/DeveloperPerson", "description": "The person the key acts as." } }, "required": [ "user", "organization", "role", "key", "limits" ], "type": "object" }, "DeveloperPerson": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name", "email" ], "type": "object" }, "DeveloperOrganization": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "slug", "name" ], "type": "object" }, "DeveloperLimits": { "additionalProperties": false, "properties": { "requestsPerMinute": { "description": "The most requests a minute this key may make.", "format": "int64", "type": "integer" }, "rowBudget": { "$ref": "#/components/schemas/Budget" } }, "required": [ "requestsPerMinute", "rowBudget" ], "type": "object" }, "Budget": { "additionalProperties": false, "properties": { "left": { "description": "Rows left; requests that return rows are refused at zero.", "format": "int64", "type": "integer" }, "perDay": { "description": "The most data rows this person’s keys may read in a day in this organization.", "format": "int64", "type": "integer" }, "used": { "description": "Rows read in the last 24 hours.", "format": "int64", "type": "integer" } }, "required": [ "perDay", "used", "left" ], "type": "object" }, "DeveloperKey": { "additionalProperties": false, "properties": { "expiresAt": { "format": "date-time", "type": "string" }, "hint": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "temporary": { "description": "A playground key.", "type": "boolean" } }, "required": [ "id", "name", "hint", "scopes", "temporary", "expiresAt" ], "type": "object" }, "WebsiteDetailForCode": { "additionalProperties": false, "properties": { "collections": { "items": { "$ref": "#/components/schemas/WebsiteCollectionForCode" }, "type": [ "array", "null" ] }, "domains": { "description": "Its custom domains that are live.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "id": { "type": "string" }, "live": { "description": "Readers can reach it now.", "type": "boolean" }, "liveAt": { "format": "date-time", "type": [ "string", "null" ] }, "liveNumber": { "description": "The release readers see. Absent until it’s published.", "format": "int32", "type": [ "integer", "null" ] }, "name": { "type": "string" }, "pageCount": { "format": "int32", "type": "integer" }, "pages": { "items": { "$ref": "#/components/schemas/WebsitePageForCode" }, "type": [ "array", "null" ] }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "domains", "pages", "collections", "id", "name", "live", "liveNumber", "liveAt", "pageCount", "updatedAt" ], "type": "object" }, "WebsitePageForCode": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "path": { "type": "string" }, "title": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "path", "title", "updatedAt" ], "type": "object" }, "WebsiteCollectionForCode": { "additionalProperties": false, "properties": { "entries": { "format": "int32", "type": "integer" }, "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "key", "name", "entries" ], "type": "object" }, "DeveloperListWebsiteForCode": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/WebsiteForCode" }, "type": [ "array", "null" ] }, "truncated": { "description": "More match than this list holds, and it can’t be paged further; search with more specific words.", "type": "boolean" } }, "required": [ "items", "truncated" ], "type": "object" }, "WebsiteForCode": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "live": { "description": "Readers can reach it now.", "type": "boolean" }, "liveAt": { "format": "date-time", "type": [ "string", "null" ] }, "liveNumber": { "description": "The release readers see. Absent until it’s published.", "format": "int32", "type": [ "integer", "null" ] }, "name": { "type": "string" }, "pageCount": { "format": "int32", "type": "integer" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "name", "live", "liveNumber", "liveAt", "pageCount", "updatedAt" ], "type": "object" }, "DeveloperReportDetailView": { "additionalProperties": false, "properties": { "description": { "type": "string" }, "document": { "description": "A Report document (@halo/spec)." }, "id": { "type": "string" }, "publishedAt": { "format": "date-time", "type": "string" }, "status": { "type": "string" }, "title": { "type": "string" }, "version": { "description": "Which version this is.", "enum": [ "published", "draft" ], "type": "string" }, "workspace": { "type": "string" } }, "required": [ "version", "document", "id", "title", "description", "status", "workspace" ], "type": "object" }, "DeveloperListDeveloperReportView": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/DeveloperReportView" }, "type": [ "array", "null" ] }, "truncated": { "description": "More match than this list holds, and it can’t be paged further; search with more specific words.", "type": "boolean" } }, "required": [ "items", "truncated" ], "type": "object" }, "DeveloperReportView": { "additionalProperties": false, "properties": { "description": { "type": "string" }, "id": { "type": "string" }, "publishedAt": { "format": "date-time", "type": "string" }, "status": { "type": "string" }, "title": { "type": "string" }, "workspace": { "type": "string" } }, "required": [ "id", "title", "description", "status", "workspace" ], "type": "object" }, "ListingForCode": { "additionalProperties": false, "properties": { "address": { "type": "string" }, "businessId": { "type": [ "string", "null" ] }, "businessName": { "type": "string" }, "city": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "data": { "additionalProperties": {}, "description": "The fields its kind adds, which the organization defines.", "type": "object" }, "description": { "type": "string" }, "endsAt": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": "string" }, "kind": { "type": "string" }, "lat": { "format": "double", "type": [ "number", "null" ] }, "lng": { "format": "double", "type": [ "number", "null" ] }, "name": { "type": "string" }, "phone": { "description": "The number its page gives visitors. Contacts’ and a business’s own numbers aren’t here.", "type": "string" }, "postalCode": { "type": "string" }, "region": { "type": "string" }, "slug": { "type": "string" }, "stale": { "description": "Nobody has confirmed it for longer than its kind allows.", "type": "boolean" }, "startsAt": { "description": "Set for happenings, such as events.", "format": "date-time", "type": [ "string", "null" ] }, "status": { "enum": [ "draft", "published", "archived" ], "type": "string" }, "summary": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "updatedAt": { "format": "date-time", "type": "string" }, "verifiedAt": { "description": "When someone last confirmed it.", "format": "date-time", "type": [ "string", "null" ] }, "website": { "type": "string" } }, "required": [ "id", "kind", "name", "slug", "status", "summary", "description", "website", "phone", "address", "city", "postalCode", "region", "lat", "lng", "startsAt", "endsAt", "tags", "data", "businessId", "verifiedAt", "stale", "createdAt", "updatedAt" ], "type": "object" }, "DeveloperPageListingForCode": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/ListingForCode" }, "type": [ "array", "null" ] }, "nextCursor": { "description": "Pass as cursor for the next page. Absent at the end.", "type": "string" } }, "required": [ "items" ], "type": "object" }, "DeveloperQueryBody": { "additionalProperties": false, "properties": { "countRows": { "description": "Also count every row the query returns (stats.total). Runs a second query.", "type": "boolean" }, "cursor": { "description": "A previous window’s stats.nextCursor. offset must be where that window ended.", "maxLength": 8192, "type": "string" }, "dimensions": { "description": "Groupings, outermost first.", "items": { "$ref": "#/components/schemas/Dimension" }, "type": [ "array", "null" ] }, "filters": { "description": "Conditions every row must meet.", "items": { "$ref": "#/components/schemas/Filter" }, "type": [ "array", "null" ] }, "keyset": { "description": "Page by rows rather than by skipping them: each window with more to come has a stats.nextCursor to send back as cursor.", "type": "boolean" }, "limit": { "description": "Most rows to return, at most 1,000. Default 100.", "format": "int64", "maximum": 1000, "minimum": 1, "type": "integer" }, "measures": { "description": "Numbers to aggregate per group.", "items": { "$ref": "#/components/schemas/Measure" }, "type": [ "array", "null" ] }, "offset": { "description": "Rows to skip, for paging.", "format": "int64", "minimum": 0, "type": "integer" }, "sorts": { "description": "Row order, in priority order.", "items": { "$ref": "#/components/schemas/Sort" }, "type": [ "array", "null" ] }, "timeZone": { "description": "The zone dates group and relative ranges resolve in. Defaults to the organization’s.", "type": "string" }, "totals": { "description": "Also aggregate the measures over every row the query returns (totals). Runs a second query.", "type": "boolean" } }, "type": "object" }, "DeveloperDatasetDetailView": { "additionalProperties": false, "properties": { "connection": { "description": "The connection it reads, by name.", "type": "string" }, "defaultDateField": { "type": "string" }, "description": { "type": "string" }, "fieldCount": { "format": "int32", "type": "integer" }, "fields": { "description": "Its fields. Hidden ones are left out and can’t be queried.", "items": { "$ref": "#/components/schemas/DeveloperFieldView" }, "type": [ "array", "null" ] }, "id": { "type": "string" }, "level": { "description": "The person’s access to it.", "enum": [ "none", "view", "edit", "manage" ], "type": "string" }, "marketplaceData": { "description": "Marketplace data: its fields can be read, and its rows only in Halo.", "type": "boolean" }, "name": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "fields", "id", "name", "description", "fieldCount", "connection", "marketplaceData", "level", "updatedAt" ], "type": "object" }, "DeveloperFieldView": { "additionalProperties": false, "properties": { "aggregate": { "description": "How a measure adds up by default.", "type": "string" }, "description": { "type": "string" }, "format": { "type": "string" }, "label": { "type": "string" }, "name": { "description": "What queries call it.", "type": "string" }, "role": { "enum": [ "dimension", "measure" ], "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "label", "role", "type" ], "type": "object" }, "DeveloperListDeveloperDatasetView": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/DeveloperDatasetView" }, "type": [ "array", "null" ] }, "truncated": { "description": "More match than this list holds, and it can’t be paged further; search with more specific words.", "type": "boolean" } }, "required": [ "items", "truncated" ], "type": "object" }, "DeveloperDatasetView": { "additionalProperties": false, "properties": { "connection": { "description": "The connection it reads, by name.", "type": "string" }, "description": { "type": "string" }, "fieldCount": { "format": "int32", "type": "integer" }, "id": { "type": "string" }, "level": { "description": "The person’s access to it.", "enum": [ "none", "view", "edit", "manage" ], "type": "string" }, "marketplaceData": { "description": "Marketplace data: its fields can be read, and its rows only in Halo.", "type": "boolean" }, "name": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "name", "description", "fieldCount", "connection", "marketplaceData", "level", "updatedAt" ], "type": "object" }, "DeveloperQueryResult": { "additionalProperties": false, "properties": { "columns": { "items": { "$ref": "#/components/schemas/Column" }, "type": [ "array", "null" ] }, "rows": { "description": "An array per row, in column order.", "items": { "items": {}, "type": [ "array", "null" ] }, "type": [ "array", "null" ] }, "stats": { "$ref": "#/components/schemas/DeveloperQueryStats" }, "totals": { "additionalProperties": {}, "description": "The measures over every row, by column key. Set when the request asked for totals.", "type": "object" }, "warnings": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "columns", "rows", "stats", "warnings" ], "type": "object" }, "DeveloperQueryStats": { "additionalProperties": false, "properties": { "cached": { "description": "The result came from Halo’s cache, not the source.", "type": "boolean" }, "computedAt": { "description": "When the source answered.", "format": "date-time", "type": "string" }, "durationMs": { "format": "int64", "type": "integer" }, "hasMore": { "description": "More rows follow; ask with offset, or keyset and cursor.", "type": "boolean" }, "nextCursor": { "description": "Pass as cursor for the next page, for keyset requests with more rows.", "type": "string" }, "rowCount": { "format": "int64", "type": "integer" }, "timeZone": { "type": "string" }, "total": { "description": "Every row the query returns. Set when the request asked for countRows.", "format": "int64", "type": "integer" }, "totalEstimated": { "description": "total is the source’s estimate, for results too big to count cheaply.", "type": "boolean" } }, "required": [ "durationMs", "rowCount", "hasMore", "cached", "timeZone" ], "type": "object" }, "DeveloperChartDetailView": { "additionalProperties": false, "properties": { "datasetId": { "type": "string" }, "datasetName": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "problems": { "description": "Why it can’t run against its dataset’s current version, such as a field that’s gone. Empty when it runs.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "spec": { "$ref": "#/components/schemas/Visualization" }, "type": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "spec", "problems", "id", "name", "description", "type", "datasetId", "datasetName", "updatedAt" ], "type": "object" }, "Visualization": { "additionalProperties": false, "properties": { "datasetId": { "type": "string" }, "datasetVersion": { "format": "int64", "type": "integer" }, "description": { "type": "string" }, "fields": { "$ref": "#/components/schemas/VisualizationFields" }, "filters": { "items": { "$ref": "#/components/schemas/Filter" }, "type": [ "array", "null" ] }, "goals": { "items": { "$ref": "#/components/schemas/VisualizationGoalsElem" }, "type": [ "array", "null" ] }, "id": { "type": "string" }, "limit": { "format": "int64", "type": "integer" }, "options": { "$ref": "#/components/schemas/VisualizationOptions" }, "sorts": { "items": { "$ref": "#/components/schemas/Sort" }, "type": [ "array", "null" ] }, "specVersion": { "format": "double", "type": "number" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "datasetId", "fields", "specVersion", "type" ], "type": "object" }, "VisualizationOptions": { "additionalProperties": false, "properties": { "bands": { "items": { "$ref": "#/components/schemas/VisualizationOptionsBandsElem" }, "type": [ "array", "null" ] }, "basemap": { "type": "boolean" }, "binWidth": { "format": "double", "type": "number" }, "boundaries": { "type": "string" }, "code": { "type": "string" }, "colorRules": { "items": { "$ref": "#/components/schemas/VisualizationOptionsColorRulesElem" }, "type": [ "array", "null" ] }, "colors": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "comparison": { "type": "string" }, "crossFilter": { "type": "boolean" }, "dateField": { "type": "string" }, "forecast": { "$ref": "#/components/schemas/VisualizationOptionsForecast" }, "mapLayer": { "type": "string" }, "max": { "format": "double", "type": "number" }, "maxSlices": { "format": "int64", "type": "integer" }, "min": { "format": "double", "type": "number" }, "movingAverage": { "format": "int64", "type": "integer" }, "numberFormat": { "type": "string" }, "orientation": { "type": "string" }, "referenceLines": { "items": { "$ref": "#/components/schemas/VisualizationOptionsReferenceLinesElem" }, "type": [ "array", "null" ] }, "regionSetId": { "type": "string" }, "seriesColors": { "additionalProperties": { "format": "int64", "type": "integer" }, "type": "object" }, "showLabels": { "type": "boolean" }, "showLegend": { "type": "boolean" }, "showTotals": { "type": "boolean" }, "smooth": { "type": "boolean" }, "sparkline": { "type": "boolean" }, "stacked": { "type": "boolean" }, "target": { "format": "double", "type": "number" }, "trend": { "type": "string" }, "zoom": { "type": "boolean" } }, "type": "object" }, "VisualizationOptionsReferenceLinesElem": { "additionalProperties": false, "properties": { "kind": { "type": "string" }, "label": { "type": "string" }, "value": { "format": "double", "type": "number" } }, "required": [ "kind" ], "type": "object" }, "VisualizationOptionsForecast": { "additionalProperties": false, "properties": { "method": { "type": "string" }, "periods": { "format": "int64", "type": "integer" } }, "required": [ "periods" ], "type": "object" }, "VisualizationOptionsColorRulesElem": { "additionalProperties": false, "properties": { "label": { "type": "string" }, "op": { "type": "string" }, "status": { "type": "string" }, "to": { "format": "double", "type": "number" }, "value": { "format": "double", "type": "number" } }, "required": [ "op", "status", "value" ], "type": "object" }, "VisualizationOptionsBandsElem": { "additionalProperties": false, "properties": { "label": { "type": "string" }, "to": { "format": "double", "type": "number" } }, "required": [ "to" ], "type": "object" }, "VisualizationGoalsElem": { "additionalProperties": false, "properties": { "goalId": { "type": "string" } }, "required": [ "goalId" ], "type": "object" }, "VisualizationFields": { "additionalProperties": false, "properties": { "columns": { "items": { "$ref": "#/components/schemas/Dimension" }, "type": [ "array", "null" ] }, "dimensions": { "items": { "$ref": "#/components/schemas/Dimension" }, "type": [ "array", "null" ] }, "measures": { "items": { "$ref": "#/components/schemas/VisualizationMeasure" }, "type": [ "array", "null" ] }, "series": { "$ref": "#/components/schemas/Dimension" } }, "type": "object" }, "VisualizationMeasure": { "additionalProperties": false, "properties": { "aggregate": { "type": "string" }, "alias": { "type": "string" }, "axis": { "type": "string" }, "field": { "type": "string" }, "mark": { "type": "string" } }, "required": [ "field" ], "type": "object" }, "DeveloperListDeveloperChartView": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/DeveloperChartView" }, "type": [ "array", "null" ] }, "truncated": { "description": "More match than this list holds, and it can’t be paged further; search with more specific words.", "type": "boolean" } }, "required": [ "items", "truncated" ], "type": "object" }, "DeveloperChartView": { "additionalProperties": false, "properties": { "datasetId": { "type": "string" }, "datasetName": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "name", "description", "type", "datasetId", "datasetName", "updatedAt" ], "type": "object" }, "BusinessDetailForCode": { "additionalProperties": false, "properties": { "city": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "listingCount": { "format": "int32", "type": "integer" }, "listings": { "items": { "$ref": "#/components/schemas/ListingForCode" }, "type": [ "array", "null" ] }, "name": { "type": "string" }, "postalCode": { "type": "string" }, "region": { "type": "string" }, "status": { "enum": [ "prospect", "active", "paused", "closed" ], "type": "string" }, "summary": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "updatedAt": { "format": "date-time", "type": "string" }, "website": { "type": "string" } }, "required": [ "listings", "id", "name", "status", "summary", "website", "city", "postalCode", "region", "tags", "listingCount", "createdAt", "updatedAt" ], "type": "object" }, "Problem": { "additionalProperties": false, "properties": { "code": { "description": "Stable machine-readable error code.", "type": "string" }, "detail": { "description": "Explanation specific to this occurrence.", "type": "string" }, "editions": { "description": "For editions_affected: the published editions that read this dataset.", "items": { "$ref": "#/components/schemas/AffectedEditionView" }, "type": [ "array", "null" ] }, "errors": { "description": "Field-level validation errors, and mistakes in SQL someone wrote.", "items": { "$ref": "#/components/schemas/ErrorDetail" }, "type": [ "array", "null" ] }, "expiredAt": { "description": "For link_expired: when it stopped working.", "format": "date-time", "type": "string" }, "feature": { "description": "For plan_feature_unavailable: the feature the plan doesn’t include.", "type": "string" }, "limit": { "$ref": "#/components/schemas/PlanLimit", "description": "For plan_limit_reached: the limit, its cap and what’s in use." }, "organization": { "$ref": "#/components/schemas/ProblemOrg", "description": "For link_expired: the organization whose link it was, so the page saying so can wear its brand." }, "requestId": { "description": "The request’s id, also in X-Request-Id. Quote it to Halo.", "type": "string" }, "saveConflict": { "$ref": "#/components/schemas/SaveConflict", "description": "For revision_conflict, in every product: the save your copy doesn’t have, and who made it." }, "signInMethods": { "description": "For sign_in_method_not_allowed and sign_in_method_required: the sign-in methods that are allowed.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "status": { "description": "HTTP status code.", "format": "int64", "type": "integer" }, "title": { "description": "The HTTP status in words.", "type": "string" }, "trash": { "$ref": "#/components/schemas/TrashRef", "description": "For in_trash: the item in the Trash, and whether you can restore it." }, "type": { "description": "A URI identifying the problem type: https://usehalo.net/problems/{code}.", "type": "string" }, "websites": { "description": "For editions_affected: the live websites showing numbers from this dataset.", "items": { "$ref": "#/components/schemas/AffectedWebsiteView" }, "type": [ "array", "null" ] } }, "required": [ "title", "status", "code" ], "type": "object" }, "AffectedWebsiteView": { "additionalProperties": false, "properties": { "canWithdraw": { "description": "You may take the dataset’s numbers off it. Otherwise it keeps them, and whoever answers for them is told.", "type": "boolean" }, "id": { "type": "string" }, "name": { "type": "string" }, "url": { "description": "Its settings in Halo CMS, where its data sources are.", "type": "string" } }, "required": [ "id", "name", "url", "canWithdraw" ], "type": "object" }, "TrashRef": { "additionalProperties": false, "properties": { "canRestore": { "description": "Whether you may restore it.", "type": "boolean" }, "id": { "type": "string" }, "kind": { "enum": [ "goal", "report", "chart", "dataset", "connection", "table", "asset", "folder", "workspace" ], "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name", "canRestore" ], "type": "object" }, "SaveConflict": { "additionalProperties": false, "properties": { "revision": { "description": "The latest revision or version. Send it back, with overwrite, to save on top of it on purpose.", "format": "int64", "type": "integer" }, "savedAt": { "format": "date-time", "type": "string" }, "savedBy": { "description": "Who saved it.", "type": "string" } }, "required": [ "revision", "savedBy", "savedAt" ], "type": "object" }, "ProblemOrg": { "additionalProperties": false, "properties": { "logoUrl": { "type": "string" }, "name": { "type": "string" }, "showBadge": { "description": "Show Powered by Halo: unless the plan removes it, as on the report itself.", "type": "boolean" }, "theme": { "$ref": "#/components/schemas/Theme" } }, "required": [ "name", "theme", "showBadge" ], "type": "object" }, "PlanLimit": { "additionalProperties": false, "properties": { "cap": { "description": "What the plan includes, in unit.", "format": "int64", "type": "integer" }, "key": { "description": "The limit, such as seats or exports_per_day.", "type": "string" }, "unit": { "enum": [ "count", "bytes", "credits" ], "type": "string" }, "used": { "description": "What’s in use already, in unit; for daily and monthly limits, this period’s.", "format": "int64", "type": "integer" } }, "required": [ "key", "cap", "used", "unit" ], "type": "object" }, "ErrorDetail": { "additionalProperties": false, "properties": { "location": { "description": "Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'", "type": "string" }, "message": { "description": "Error message text", "type": "string" }, "sql": { "$ref": "#/components/schemas/SQLErrorLocation", "description": "Set for mistakes in SQL someone wrote: which SQL, and where in it." }, "value": { "description": "The value at the given location" } }, "type": "object" }, "SQLErrorLocation": { "additionalProperties": false, "properties": { "code": { "description": "The source’s error code, such as a Postgres SQLSTATE.", "type": "string" }, "column": { "description": "1-based column on that line, counted in characters (Unicode code points).", "format": "int64", "minimum": 1, "type": "integer" }, "field": { "description": "The calculated field’s name, for target field.", "type": "string" }, "hint": { "description": "The source’s suggestion for fixing it.", "type": "string" }, "line": { "description": "1-based line the source pointed at. Absent when it didn’t point at a place.", "format": "int64", "minimum": 1, "type": "integer" }, "target": { "description": "source: the dataset’s custom SQL query; field: a calculated field’s SQL expression.", "enum": [ "source", "field" ], "type": "string" } }, "required": [ "target" ], "type": "object" }, "AffectedEditionView": { "additionalProperties": false, "properties": { "canWithdraw": { "description": "You may withdraw it. Otherwise it’s kept, and its owners are told.", "type": "boolean" }, "id": { "type": "string" }, "label": { "type": "string" }, "report": { "description": "Its report’s title. Empty when you can’t open the report.", "type": "string" }, "reportId": { "type": "string" } }, "required": [ "id", "reportId", "report", "label", "canWithdraw" ], "type": "object" }, "DeveloperPageBusinessForCode": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/BusinessForCode" }, "type": [ "array", "null" ] }, "nextCursor": { "description": "Pass as cursor for the next page. Absent at the end.", "type": "string" } }, "required": [ "items" ], "type": "object" }, "BusinessForCode": { "additionalProperties": false, "properties": { "city": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "listingCount": { "format": "int32", "type": "integer" }, "name": { "type": "string" }, "postalCode": { "type": "string" }, "region": { "type": "string" }, "status": { "enum": [ "prospect", "active", "paused", "closed" ], "type": "string" }, "summary": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "updatedAt": { "format": "date-time", "type": "string" }, "website": { "type": "string" } }, "required": [ "id", "name", "status", "summary", "website", "city", "postalCode", "region", "tags", "listingCount", "createdAt", "updatedAt" ], "type": "object" } }, "securitySchemes": { "apiKey": { "bearerFormat": "hak_…", "description": "An API key, for the Developer API. Make one at dev.usehalo.net/keys.", "scheme": "bearer", "type": "http" }, "shareToken": { "description": "A report link’s token (hlp_…, hle_…) or a signed embed token, for the public report API.", "scheme": "bearer", "type": "http" }, "sourceToken": { "bearerFormat": "hci_…", "description": "A Halo CRM webhook source’s token.", "scheme": "bearer", "type": "http" } } } }