{"openapi":"3.1.0","info":{"title":"Darwin public API","version":"v1","description":"Read the analytics of your Darwin projects.\n\nThe API is **experimental**: a method, a field or a limit can change or go without notice.\n\nEvery call needs an API key. Create one on the key management page at `/`, then send it as\n`Authorization: Bearer <key>`. A key reads the organizations you chose when you created it, as\nlong as you can still read them.\n\nA REST call answers `{ \"result\": … }`. A JSON-RPC call answers the same `result` in its response\nobject. A params field that the method does not read does not fail the call: the answer adds\n`warnings`, one per field, with its `path` (`page.nextCursor`). Read `warnings`: the call ran\nwithout that field. On JSON-RPC, `warnings` is a member beside `result`, an extension of\nJSON-RPC 2.0: a generic client drops it. When the call fails, the warnings are in the `data` of\nthe error (`data.detail.warnings` on JSON-RPC).\n"},"servers":[{"url":"https://developer.darwindata.ai/public/v1/api"}],"security":[{"apiKey":[]}],"paths":{"/projects/list":{"post":{"operationId":"projects/list","summary":"The projects your key may read, in all its organizations.","description":"Answers the projects of every organization your key reads, from the oldest to the newest.\n\nPage with `page.limit`, and send the `nextCursor` of the previous page as `page.cursor`. The last\npage has no `nextCursor`. A project created after your first page comes on the last page.\n\nThe analytics methods read a project only when its `state` is `computed`: an assessment of the\nproject completed. While a new assessment runs, the project stays `computed`, and the analytics\nmethods read the previous assessment until the snapshot of the new one is sealed.\n","tags":["projects"],"deprecated":false,"x-darwin-stability":"experimental","x-darwin-access":{"kind":"caller"},"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectsListInput"},"examples":{"example1":{"summary":"The first page","value":{}},"example2":{"summary":"Two projects per page","value":{"page":{"limit":2}}}}}}},"responses":{"200":{"description":"The result of the method, and a warning for each params field it ignored.","content":{"application/json":{"schema":{"type":"object","required":["result"],"properties":{"result":{"$ref":"#/components/schemas/ProjectSummaryList"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/Warning"}}}}}}},"400":{"description":"`PARSE_ERROR` (-32700), `INVALID_PARAMS` (-32602)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[-32700,-32602]},"class":{"enum":["PARSE_ERROR","INVALID_PARAMS"]},"message":{"type":"string"},"data":{}}}}}},"401":{"description":"`UNAUTHENTICATED` (1401)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1401]},"class":{"enum":["UNAUTHENTICATED"]},"message":{"type":"string"},"data":{}}}}}},"403":{"description":"`FORBIDDEN` (1403)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1403]},"class":{"enum":["FORBIDDEN"]},"message":{"type":"string"},"data":{}}}}}},"429":{"description":"`RATE_LIMITED` (1429)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1429]},"class":{"enum":["RATE_LIMITED"]},"message":{"type":"string"},"data":{}}}}}},"500":{"description":"`INTERNAL` (-32603)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[-32603]},"class":{"enum":["INTERNAL"]},"message":{"type":"string"},"data":{}}}}}},"503":{"description":"`UNAVAILABLE` (1503)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1503]},"class":{"enum":["UNAVAILABLE"]},"message":{"type":"string"},"data":{}}}}}}}}},"/projects/describe":{"post":{"operationId":"projects/describe","summary":"The relations projects/query can read, and the columns of one.","description":"Answers what `projects/query` can read in a project: every relation, what one row of it is, and\nworked queries.\n\nName a relation in `relation` to get its columns and their SQL types, read from the snapshot of\nthe project. The relations whose `kind` is `fold` are computed from the snapshot for the point of\nview of the query, most of them aggregations: read them rather than rebuild a total from the\ntables.\n\nThe catalogue is the same for every project. The columns need a sealed snapshot of the project:\nwith none, the answer is `NOT_READY`, and its message says whether to retry or to launch a new\nassessment. They are built within 60 seconds; past it, the answer is `UNAVAILABLE`: retry later.\n","tags":["projects"],"deprecated":false,"x-darwin-stability":"experimental","x-darwin-access":{"kind":"scoped","scope":"projectAnalytics"},"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectsDescribeInput"},"examples":{"example1":{"summary":"The catalogue","value":{"projectId":"$projectId"}},"example2":{"summary":"The columns of the risks","value":{"projectId":"$projectId","relation":"fold_risks"}}}}}},"responses":{"200":{"description":"The result of the method, and a warning for each params field it ignored.","content":{"application/json":{"schema":{"type":"object","required":["result"],"properties":{"result":{"$ref":"#/components/schemas/ProjectDescription"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/Warning"}}}}}}},"400":{"description":"`PARSE_ERROR` (-32700), `INVALID_PARAMS` (-32602)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[-32700,-32602]},"class":{"enum":["PARSE_ERROR","INVALID_PARAMS"]},"message":{"type":"string"},"data":{}}}}}},"401":{"description":"`UNAUTHENTICATED` (1401)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1401]},"class":{"enum":["UNAUTHENTICATED"]},"message":{"type":"string"},"data":{}}}}}},"403":{"description":"`FORBIDDEN` (1403)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1403]},"class":{"enum":["FORBIDDEN"]},"message":{"type":"string"},"data":{}}}}}},"409":{"description":"`NOT_READY` (1409)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1409]},"class":{"enum":["NOT_READY"]},"message":{"type":"string"},"data":{}}}}}},"429":{"description":"`RATE_LIMITED` (1429)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1429]},"class":{"enum":["RATE_LIMITED"]},"message":{"type":"string"},"data":{}}}}}},"500":{"description":"`INTERNAL` (-32603)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[-32603]},"class":{"enum":["INTERNAL"]},"message":{"type":"string"},"data":{}}}}}},"503":{"description":"`UNAVAILABLE` (1503)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1503]},"class":{"enum":["UNAVAILABLE"]},"message":{"type":"string"},"data":{}}}}}}}}},"/projects/query":{"post":{"operationId":"projects/query","summary":"One read-only SQL query over the analytics of a project.","description":"Runs one read-only SQL query over the analytics of a project, and answers its rows as JSON\nobjects, one page at a time.\n\n- `sql` is one `SELECT` over the relations of `projects/describe`, or a `UNION`, `EXCEPT` or\n  `INTERSECT` of them, with an optional `WITH`. A statement that writes, a second statement, and\n  a read of a file outside the project's own analytics are refused with `INVALID_QUERY`. So is a\n  query that fails on its own text, and a single row larger than 4 MiB as JSON.\n- The query reads the point of view of `entityId` and its subtree, or of the whole project when\n  `entityId` is absent, with `net` or `gross` ownership.\n- It reads the latest sealed snapshot of the project, which can belong to an assessment that still\n  runs. With none, the answer is `NOT_READY`, and its message says why. While an assessment runs,\n  retry later. When the last assessment left no analytics this version can read, or no\n  assessment completed, a retry answers the same thing: launch a new assessment.\n\nThe numbers are the ones the screens compute, with three differences:\n\n- The risks a user excluded are not in `fold_risks` and `risk_rows`. The screens keep them in\n  their totals, so a total here can be lower.\n- An entity with no dependency data of its own has no row in `fold_dependencies`. The screens\n  show a sector estimate for it.\n- The relations carry no sourcing risk: the screens add it to the commodities.\n\nLimits:\n\n- The relations the query names are built first, within 60 seconds. Past it, the answer is\n  `UNAVAILABLE`: retry later.\n- The query then has 30 seconds. Past it, the answer is `QUERY_TIMEOUT`. A query that runs out of\n  memory answers `QUERY_TOO_LARGE`. Narrow the query in both cases, because a retry fails the same\n  way.\n- A call waits 5 seconds at most for a free connection, then answers `UNAVAILABLE`.\n\nPage with `page.limit`, and send the `nextCursor` of the previous page as `page.cursor`. Send the\nsame `sql`, `entityId` and `ownershipView` with it. The last page has no `nextCursor`. The cursor\ncounts rows: order the rows on a unique key, or a row can move between two pages. A page stops early\nwhen its rows hold more than 4 MiB as JSON: follow its `nextCursor`. When a new assessment replaces\nthe snapshot between two pages, the cursor answers `INVALID_PARAMS`: start again from the first\npage.","tags":["projects"],"deprecated":false,"x-darwin-stability":"experimental","x-darwin-access":{"kind":"scoped","scope":"projectAnalytics"},"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectsQueryInput"},"examples":{"example1":{"summary":"The impact by IPBES pressure","value":{"projectId":"$projectId","sql":"SELECT ipbes_pressure, value FROM dash_ipbes ORDER BY value DESC"}},"example2":{"summary":"The ten largest pressures, gross","value":{"projectId":"$projectId","ownershipView":"gross","sql":"SELECT pressure_indicator, unit, biome, scope, net FROM fold_pressures ORDER BY abs(net) DESC, pressure_indicator, biome, scope","page":{"limit":10}}}}}}},"responses":{"200":{"description":"The result of the method, and a warning for each params field it ignored.","content":{"application/json":{"schema":{"type":"object","required":["result"],"properties":{"result":{"$ref":"#/components/schemas/RowList"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/Warning"}}}}}}},"400":{"description":"`PARSE_ERROR` (-32700), `INVALID_PARAMS` (-32602)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[-32700,-32602]},"class":{"enum":["PARSE_ERROR","INVALID_PARAMS"]},"message":{"type":"string"},"data":{}}}}}},"401":{"description":"`UNAUTHENTICATED` (1401)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1401]},"class":{"enum":["UNAUTHENTICATED"]},"message":{"type":"string"},"data":{}}}}}},"403":{"description":"`FORBIDDEN` (1403)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1403]},"class":{"enum":["FORBIDDEN"]},"message":{"type":"string"},"data":{}}}}}},"404":{"description":"`NOT_FOUND` (1404)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1404]},"class":{"enum":["NOT_FOUND"]},"message":{"type":"string"},"data":{}}}}}},"408":{"description":"`QUERY_TIMEOUT` (1408)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1408]},"class":{"enum":["QUERY_TIMEOUT"]},"message":{"type":"string"},"data":{}}}}}},"409":{"description":"`NOT_READY` (1409)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1409]},"class":{"enum":["NOT_READY"]},"message":{"type":"string"},"data":{}}}}}},"413":{"description":"`QUERY_TOO_LARGE` (1413)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1413]},"class":{"enum":["QUERY_TOO_LARGE"]},"message":{"type":"string"},"data":{}}}}}},"422":{"description":"`INVALID_QUERY` (1422)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1422]},"class":{"enum":["INVALID_QUERY"]},"message":{"type":"string"},"data":{}}}}}},"429":{"description":"`RATE_LIMITED` (1429)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1429]},"class":{"enum":["RATE_LIMITED"]},"message":{"type":"string"},"data":{}}}}}},"500":{"description":"`INTERNAL` (-32603)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[-32603]},"class":{"enum":["INTERNAL"]},"message":{"type":"string"},"data":{}}}}}},"503":{"description":"`UNAVAILABLE` (1503)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1503]},"class":{"enum":["UNAVAILABLE"]},"message":{"type":"string"},"data":{}}}}}}}}},"/projects/export":{"post":{"operationId":"projects/export","summary":"One read-only SQL query over the analytics of a project, as a parquet file.","description":"Runs one read-only SQL query over the analytics of a project, writes all its rows to one parquet\nfile, and answers a URL to download it. Use it for a relation too large to page with\n`projects/query`.\n\n- `sql`, `entityId` and `ownershipView` are those of `projects/query`, with the same rules and the\n  same three differences from the screens. There is no page and no 4 MiB limit on a row: the file\n  holds every row.\n- The answer is `url`, `expiresAt`, `rows` and `bytes`. Download the file with a `GET` on `url`\n  and the header `Authorization: Bearer <key>`: the key of the call, or another key of the same\n  owner that still reads the project. In DuckDB, create the secret first:\n  `CREATE SECRET (TYPE http, BEARER_TOKEN '<key>')`, then `SELECT * FROM read_parquet('<url>')`.\n- The download answers the whole file and ignores `Range`. It counts in the usage of the key, not\n  in its quota. A `HEAD` on `url` answers the size in `Content-Length` and counts no download.\n- The URL stops working at `expiresAt`, 15 minutes after the call. For one day after, it answers\n  `410` with the class `LINK_EXPIRED`, then `404`. Call again for a new URL.\n- A download with no key answers `401`. A URL this service never handed out, or one of another\n  owner, answers `404` with the class `NOT_FOUND`. `503` `UNAVAILABLE` means retry later.\n- Each call writes a new file. The storage removes it about one day later.\n\nLimits:\n\n- The relations the query names are built first, within 60 seconds. Past it, the answer is\n  `UNAVAILABLE`: retry later.\n- The query then has 120 seconds. Past it, the answer is `QUERY_TIMEOUT`. A query that runs out of\n  memory answers `QUERY_TOO_LARGE`. So does a file that grows past 1 GiB: the query stops there.\n  Narrow the query in both cases, because a retry fails the same way.\n- A call waits 5 seconds at most for a free connection, then answers `UNAVAILABLE`.\n","tags":["projects"],"deprecated":false,"x-darwin-stability":"experimental","x-darwin-access":{"kind":"scoped","scope":"projectAnalytics"},"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectsExportInput"},"examples":{"example1":{"summary":"Every dependency row of the project","value":{"projectId":"$projectId","sql":"SELECT * FROM dependency_rows"}}}}}},"responses":{"200":{"description":"The result of the method, and a warning for each params field it ignored.","content":{"application/json":{"schema":{"type":"object","required":["result"],"properties":{"result":{"$ref":"#/components/schemas/ProjectExport"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/Warning"}}}}}}},"400":{"description":"`PARSE_ERROR` (-32700), `INVALID_PARAMS` (-32602)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[-32700,-32602]},"class":{"enum":["PARSE_ERROR","INVALID_PARAMS"]},"message":{"type":"string"},"data":{}}}}}},"401":{"description":"`UNAUTHENTICATED` (1401)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1401]},"class":{"enum":["UNAUTHENTICATED"]},"message":{"type":"string"},"data":{}}}}}},"403":{"description":"`FORBIDDEN` (1403)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1403]},"class":{"enum":["FORBIDDEN"]},"message":{"type":"string"},"data":{}}}}}},"404":{"description":"`NOT_FOUND` (1404)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1404]},"class":{"enum":["NOT_FOUND"]},"message":{"type":"string"},"data":{}}}}}},"408":{"description":"`QUERY_TIMEOUT` (1408)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1408]},"class":{"enum":["QUERY_TIMEOUT"]},"message":{"type":"string"},"data":{}}}}}},"409":{"description":"`NOT_READY` (1409)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1409]},"class":{"enum":["NOT_READY"]},"message":{"type":"string"},"data":{}}}}}},"413":{"description":"`QUERY_TOO_LARGE` (1413)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1413]},"class":{"enum":["QUERY_TOO_LARGE"]},"message":{"type":"string"},"data":{}}}}}},"422":{"description":"`INVALID_QUERY` (1422)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1422]},"class":{"enum":["INVALID_QUERY"]},"message":{"type":"string"},"data":{}}}}}},"429":{"description":"`RATE_LIMITED` (1429)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1429]},"class":{"enum":["RATE_LIMITED"]},"message":{"type":"string"},"data":{}}}}}},"500":{"description":"`INTERNAL` (-32603)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[-32603]},"class":{"enum":["INTERNAL"]},"message":{"type":"string"},"data":{}}}}}},"503":{"description":"`UNAVAILABLE` (1503)","content":{"application/json":{"schema":{"type":"object","required":["code","class","message"],"properties":{"code":{"enum":[1503]},"class":{"enum":["UNAVAILABLE"]},"message":{"type":"string"},"data":{}}}}}}}}}},"components":{"schemas":{"ProjectsListInput":{"type":"object","properties":{"page":{"type":"object","properties":{"limit":{"type":"integer","format":"uint32","minimum":1,"maximum":500,"default":100,"description":"How many items to return."},"cursor":{"anyOf":[{"$ref":"#/components/schemas/Cursor"},{"type":"null"}],"description":"The `nextCursor` of the previous page, sent as `page.cursor`. Omit it for the first page."}},"description":"Which page to return. Omit it for the first page, at the default size.","default":{"limit":100}}},"description":"The projects that the key may read, one page at a time."},"Cursor":{"type":"string","description":"A position in a list, as the previous page returned it. The caller never builds one."},"ProjectSummaryList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ProjectSummary"},"description":"The items of this page. Empty when the list is empty."},"nextCursor":{"anyOf":[{"$ref":"#/components/schemas/Cursor"},{"type":"null"}],"description":"Absent on the last page."}},"required":["items"],"description":"One page of a list."},"ProjectSummary":{"type":"object","properties":{"projectId":{"$ref":"#/components/schemas/ProjectId","description":"The id of the project, a UUID."},"name":{"type":"string","description":"The name of the project, as Darwin shows it."},"organization":{"$ref":"#/components/schemas/OrganizationKey","description":"The key of the organization that owns the project."},"state":{"$ref":"#/components/schemas/ProjectState","description":"Whether the analytics methods can read the project now."}},"required":["projectId","name","organization","state"],"description":"One project the key may read."},"ProjectId":{"type":"string","format":"uuid"},"OrganizationKey":{"type":"string","description":"The key of an organization, such as `darwin`."},"ProjectState":{"oneOf":[{"type":"string","const":"computed","description":"An assessment completed: the analytics methods can read the project. While a new\nassessment runs, they read the previous one until the snapshot of the new one is sealed."},{"type":"string","const":"computing","description":"The first assessment runs: nothing can be read yet."},{"type":"string","const":"notComputed","description":"No assessment completed, and none runs: nothing can be read."}],"description":"Whether the analytics methods can read the project. They read the snapshot of the last\ncompleted assessment."},"ProjectsDescribeInput":{"type":"object","properties":{"projectId":{"$ref":"#/components/schemas/ProjectId","description":"The id of the project, a UUID. `projects/list` gives the ids your key may read."},"relation":{"type":["string","null"],"description":"A relation of the catalogue, e.g. `fold_risks`. Give it to get its columns and their types.","default":null}},"required":["projectId"],"description":"The project to describe, and optionally one of its relations."},"ProjectDescription":{"type":"object","properties":{"relations":{"type":"array","items":{"$ref":"#/components/schemas/RelationSummary"},"description":"Every relation a query may read, the computed ones first."},"examples":{"type":"array","items":{"$ref":"#/components/schemas/QueryExample"},"description":"Worked queries, each with the question it answers."},"columns":{"type":["array","null"],"items":{"$ref":"#/components/schemas/Column"},"description":"The columns of the relation of the input, in order. Absent when the input names none."}},"required":["relations","examples"],"description":"The catalogue of the relations, and the columns of one relation when the input names one."},"RelationSummary":{"type":"object","properties":{"name":{"type":"string","description":"The name to write in `FROM`."},"kind":{"$ref":"#/components/schemas/RelationKind"},"about":{"type":["string","null"],"description":"What one row is. Absent for a table, whose columns say it."}},"required":["name","kind"],"description":"One relation a query may name in `FROM`."},"RelationKind":{"oneOf":[{"type":"string","const":"fold","description":"A relation Darwin computes from the snapshot for the point of view of the query, most of\nthem aggregations. Read one rather than rebuild a total from the tables."},{"type":"string","const":"table","description":"A table of the assessment, as Darwin stored it."}]},"QueryExample":{"type":"object","properties":{"question":{"type":"string","description":"The question the query answers."},"sql":{"type":"string","description":"The `sql` to send to `projects/query`."}},"required":["question","sql"],"description":"A worked query."},"Column":{"type":"object","properties":{"name":{"type":"string","description":"The name to write in a query."},"type":{"type":"string","description":"The SQL type of the column, e.g. `VARCHAR`, `DOUBLE`, `UUID`."}},"required":["name","type"],"description":"One column of a relation."},"ProjectsQueryInput":{"type":"object","properties":{"projectId":{"$ref":"#/components/schemas/ProjectId","description":"The id of the project, a UUID. `projects/list` gives the ids your key may read."},"entityId":{"anyOf":[{"$ref":"#/components/schemas/EntityId"},{"type":"null"}],"description":"The entity whose subtree the query reads, a UUID. Omit it for the whole project.","default":null},"ownershipView":{"$ref":"#/components/schemas/OwnershipView","description":"`net` (the default) or `gross`.","default":"net"},"sql":{"type":"string","description":"One `SELECT` over the relations of `projects/describe`, or a `UNION`, `EXCEPT` or\n`INTERSECT` of them, with an optional `WITH`. Anything else is refused. Order the rows on a\nunique key to page them."},"page":{"type":"object","properties":{"limit":{"type":"integer","format":"uint32","minimum":1,"maximum":500,"default":100,"description":"How many items to return."},"cursor":{"anyOf":[{"$ref":"#/components/schemas/Cursor"},{"type":"null"}],"description":"The `nextCursor` of the previous page, sent as `page.cursor`. Omit it for the first page."}},"description":"Which page of rows to return. Omit it for the first page, at the default size. Send the\nsame `sql`, `entityId` and `ownershipView` with a `cursor`.","default":{"limit":100}}},"required":["projectId","sql"],"description":"One read-only SQL query over the analytics of a project."},"EntityId":{"type":"string","format":"uuid"},"OwnershipView":{"oneOf":[{"type":"string","const":"net","description":"Each entity counts at the ownership share along the path. The screens' default."},{"type":"string","const":"gross","description":"Each entity counts at 100%, whatever the ownership."}],"description":"Net or gross ownership."},"RowList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Row"},"description":"The items of this page. Empty when the list is empty."},"nextCursor":{"anyOf":[{"$ref":"#/components/schemas/Cursor"},{"type":"null"}],"description":"Absent on the last page."}},"required":["items"],"description":"One page of a list."},"Row":{"type":"object","additionalProperties":true,"description":"One row of the result: each column name, with its value."},"ProjectsExportInput":{"type":"object","properties":{"projectId":{"$ref":"#/components/schemas/ProjectId","description":"The id of the project, a UUID. `projects/list` gives the ids your key may read."},"entityId":{"anyOf":[{"$ref":"#/components/schemas/EntityId"},{"type":"null"}],"description":"The entity whose subtree the query reads, a UUID. Omit it for the whole project.","default":null},"ownershipView":{"$ref":"#/components/schemas/OwnershipView","description":"`net` (the default) or `gross`.","default":"net"},"sql":{"type":"string","description":"One `SELECT` over the relations of `projects/describe`, or a `UNION`, `EXCEPT` or\n`INTERSECT` of them, with an optional `WITH`. Anything else is refused."}},"required":["projectId","sql"],"description":"One read-only SQL query over the analytics of a project, written whole to one parquet file."},"ProjectExport":{"type":"object","properties":{"url":{"type":"string","description":"The URL of the parquet file, on this service. Download it with `Authorization: Bearer <key>`,\nwith a key of the same owner."},"expiresAt":{"type":"string","description":"When the URL stops working, in RFC 3339.","format":"date-time"},"rows":{"type":"integer","format":"uint64","minimum":0,"description":"The rows of the file."},"bytes":{"type":"integer","format":"uint64","minimum":0,"description":"The size of the file, in bytes."}},"required":["url","expiresAt","rows","bytes"],"description":"Where to download the file, until when, and what it holds."},"Warning":{"type":"object","properties":{"path":{"type":"string","description":"Where the params hold it, e.g. `page.nextCursor`."},"message":{"type":"string"}},"required":["path","message"],"description":"Something in the params the caller should correct. The call still ran."}},"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key of the key management page, sent as `Authorization: Bearer <key>`."}}}}