![](\"https://cdn.peaka.com/badges/partner-api-key-badge.png\"/){kind=icon}
\n\n\n"
}
}
},
"/organizations/{organizationId}": {
"get": {
"tags": [
"Organization -- Organizations"
],
"summary": "Read Organization",
"description": "Returns the specified Organization.\n\nAn Organization is the highest-level resource that can contain multiple Workspaces.\n",
"operationId": "getOrganization",
"parameters": [
{
"name": "organizationId",
"in": "path",
"description": "ID of the Organization",
"required": true,
"schema": {
"type": "string"
},
"example": "8db17e23-29de-4dab-8886-af9717e0e742"
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Organization"
},
"examples": {
"Read Organization Example": {
"description": "Read Organization Example",
"value": {
"id": "d0d3c83f-29ed-4f2e-899d-1bfa00eb3cef",
"name": "ABC Organization",
"owner": "1673d60f-a0ea-41f4-9420-c91dbc2864f5",
"createdAt": "2025-03-25T12:28:48.737355Z",
"iconFileId": null,
"description": "Default Organization"
}
}
}
}
}
}
},
"x-mint": {
"content": "\n \n\n"
}
}
},
"/organizations/{organizationId}/workspaces": {
"get": {
"tags": [
"Organization -- Workspaces"
],
"summary": "List Workspaces",
"description": "Returns all workspaces under the specified Organization.\n\nA Workspace is a collaborative environment within an Organization that groups Projects together. It facilitates team collaboration, resource management, and organization of data operations.\n\nThe hierarchical structure in Peaka is:\n\nOrganization (top-level) → Workspace → Project\n\nProjects contain data catalogs and workflows that teams manage within a Workspace.\n",
"operationId": "listWorkspaces",
"parameters": [
{
"name": "organizationId",
"in": "path",
"description": "ID of the Organization",
"required": true,
"schema": {
"type": "string"
},
"example": "d0d3c83f-29ed-4f2e-899d-1bfa00eb3cef"
}
],
"responses": {
"200": {
"description": "List of Workspaces",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Workspace"
},
"examples": {
"List Workspace Example": {
"description": "List Workspace Example",
"value": [
{
"id": "56d43968-e31d-4010-9b75-018a79a51b17",
"name": "workspace 1",
"createdBy": "1673d60f-a0ea-41f4-9420-c91dbc2864f5",
"organizationId": "d0d3c83f-29ed-4f2e-899d-1bfa00eb3cef",
"description": "sample description",
"createdAt": "2025-04-17T08:08:15.687751Z",
"defaultWorkspace": false
},
{
"id": "78cf8c83-8569-4d7c-a1ce-404dee7c5c6b",
"name": "workspace 2",
"createdBy": "1673d60f-a0ea-41f4-9420-c91dbc2864f5",
"organizationId": "d0d3c83f-29ed-4f2e-899d-1bfa00eb3cef",
"description": "sample description",
"createdAt": "2025-04-17T08:05:58.312996Z",
"defaultWorkspace": false
},
{
"id": "eaa442d7-82ac-4a65-b302-093d0465eb67",
"name": "Default Workspace",
"createdBy": "1673d60f-a0ea-41f4-9420-c91dbc2864f5",
"organizationId": "d0d3c83f-29ed-4f2e-899d-1bfa00eb3cef",
"description": "Default Workspace",
"createdAt": "2025-03-25T12:28:51.147125Z",
"defaultWorkspace": true
}
]
}
}
}
}
}
},
"x-mint": {
"content": "\n \n\n"
}
},
"post": {
"tags": [
"Organization -- Workspaces"
],
"summary": "Create Workspace",
"description": "The endpoint allows you to create a new Workspace within an Organization.\n\nA Workspace is a collaborative environment within an Organization that groups Projects together. It facilitates team collaboration, resource management, and organization of data operations.\n\nThe hierarchical structure in Peaka is:\n\nOrganization (top-level) → Workspace → Project\n\nProjects contain data catalogs and workflows that teams manage within a Workspace.\n",
"operationId": "createWorkspace",
"parameters": [
{
"name": "organizationId",
"in": "path",
"description": "Organization ID",
"required": true,
"schema": {
"type": "string"
},
"example": "d0d3c83f-29ed-4f2e-899d-1bfa00eb3cef"
}
],
"requestBody": {
"description": "Create Workspace",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspaceRequest"
},
"examples": {
"Create Workspace Example": {
"description": "Create Workspace Example",
"value": {
"name": "workspace 1",
"description": "workspace description"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Workspace"
},
"examples": {
"Create Workspace Example": {
"description": "Create Workspace Example",
"value": {
"id": "8eefb5a9-59f7-43cc-bacb-f0b0e0d1b0ea",
"name": "workspace 1",
"createdBy": "1673d60f-a0ea-41f4-9420-c91dbc2864f5",
"organizationId": "d0d3c83f-29ed-4f2e-899d-1bfa00eb3cef",
"description": "workspace description",
"createdAt": null,
"defaultWorkspace": false
}
}
}
}
}
}
},
"x-mint": {
"content": "\n \n\n"
}
}
},
"/organizations/{organizationId}/workspaces/{workspaceId}": {
"get": {
"tags": [
"Organization -- Workspaces"
],
"summary": "Read Workspace",
"description": "Returns details of a specified Workspace, which is a collaborative environment within an Organization that groups Projects together.\n\nA Workspace facilitates team collaboration, resource management, and organization of data operations.\n\nThe hierarchical structure in Peaka is:\n\nOrganization (top-level) → Workspace → Project\n\nProjects contain data catalogs and workflows that teams manage within a Workspace.\n",
"operationId": "getWorkspace",
"parameters": [
{
"name": "organizationId",
"in": "path",
"description": "Organization ID",
"required": true,
"schema": {
"type": "string"
},
"example": "d0d3c83f-29ed-4f2e-899d-1bfa00eb3cef"
},
{
"name": "workspaceId",
"in": "path",
"description": "Workspace ID",
"required": true,
"schema": {
"type": "string"
},
"example": "56d43968-e31d-4010-9b75-018a79a51b17"
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Workspace"
},
"examples": {
"Read Workspace example": {
"description": "Read Workspace example",
"value": {
"id": "8eefb5a9-59f7-43cc-bacb-f0b0e0d1b0ea",
"name": "workspace 1",
"createdBy": "1673d60f-a0ea-41f4-9420-c91dbc2864f5",
"organizationId": "d0d3c83f-29ed-4f2e-899d-1bfa00eb3cef",
"description": "workspace description",
"createdAt": null,
"defaultWorkspace": false
}
}
}
}
}
}
},
"x-mint": {
"content": "\n \n\n"
}
},
"put": {
"tags": [
"Organization -- Workspaces"
],
"summary": "Update Workspace",
"description": "Updates the specified Workspace within an Organization.\n\nA Workspace is a collaborative environment within an Organization that groups Projects together, facilitating team collaboration and resource management.\n\nThe hierarchical structure in Peaka is:\n\nOrganization (top-level) → Workspace → Project\n\nProjects contain data catalogs and workflows that teams manage within a Workspace.\n",
"operationId": "updateWorkspace",
"parameters": [
{
"name": "organizationId",
"in": "path",
"description": "Organization ID",
"required": true,
"schema": {
"type": "string"
},
"example": "d0d3c83f-29ed-4f2e-899d-1bfa00eb3cef"
},
{
"name": "workspaceId",
"in": "path",
"description": "Workspace ID",
"required": true,
"schema": {
"type": "string"
},
"example": "8eefb5a9-59f7-43cc-bacb-f0b0e0d1b0ea"
}
],
"requestBody": {
"description": "Update Workspace",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspaceRequest"
},
"examples": {
"Update Workspace Example": {
"description": "Update Workspace Example",
"value": {
"name": "workspace new name",
"description": "workspace description"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Workspace"
},
"examples": {
"Update Workspace Example": {
"description": "Update Workspace Example",
"value": {
"id": "8eefb5a9-59f7-43cc-bacb-f0b0e0d1b0ea",
"name": "workspace new name",
"createdBy": "1673d60f-a0ea-41f4-9420-c91dbc2864f5",
"organizationId": "d0d3c83f-29ed-4f2e-899d-1bfa00eb3cef",
"description": "workspace description",
"createdAt": null,
"defaultWorkspace": false
}
}
}
}
}
}
},
"x-mint": {
"content": "\n \n\n"
}
},
"delete": {
"tags": [
"Organization -- Workspaces"
],
"summary": "Delete Workspace",
"description": "Deletes a specified Workspace within an Organization.\n\nA Workspace is a collaborative environment that groups Projects to facilitate team collaboration and resource management.\n\nThe hierarchical structure in Peaka is:\n\nOrganization (top-level) → Workspace → Project\n",
"operationId": "deleteWorkspace",
"parameters": [
{
"name": "organizationId",
"in": "path",
"description": "Organization ID",
"required": true,
"schema": {
"type": "string"
},
"example": "d0d3c83f-29ed-4f2e-899d-1bfa00eb3cef"
},
{
"name": "workspaceId",
"in": "path",
"description": "Workspace ID",
"required": true,
"schema": {
"type": "string"
},
"example": "8eefb5a9-59f7-43cc-bacb-f0b0e0d1b0ea"
}
],
"responses": {
"200": {
"description": "Successful operation"
}
},
"x-mint": {
"content": "\n \n\n"
}
}
},
"/organizations/{organizationId}/workspaces/{workspaceId}/projects": {
"get": {
"tags": [
"Organization -- Projects"
],
"summary": "List Projects",
"description": "Fetches all Projects within the given Workspace.\n\nA Project is a unit of work where queries, data tables, and semantic catalogs are managed. Projects live inside Workspaces.\n",
"operationId": "listProjects_1",
"parameters": [
{
"name": "organizationId",
"in": "path",
"description": "ID of the Organization",
"required": true,
"schema": {
"type": "string"
},
"example": "d0d3c83f-29ed-4f2e-899d-1bfa00eb3cef"
},
{
"name": "workspaceId",
"in": "path",
"description": "ID of the Workspace",
"required": true,
"schema": {
"type": "string"
},
"example": "56d43968-e31d-4010-9b75-018a79a51b17"
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Project"
}
},
"examples": {
"List of all projects": {
"description": "List of all projects",
"value": [
{
"id": "SksnYuxH",
"name": "Anapp23334",
"description": null,
"domain": "anapp2-rfto",
"webhookBaseUrl": "https://anapp2-rfto--test.api.peaka.host",
"createdAt": "2023-08-21T11:09:04.699714310Z",
"workspaceId": "d7f282d2-b392-4b5c-8cea-05f7523df2d2"
},
{
"id": "0IQ6f4QB",
"name": "App Deneme",
"description": null,
"domain": "appdeneme-wmdp",
"webhookBaseUrl": "https://appdeneme-wmdp--test.api.peaka.host",
"createdAt": "2023-12-14T12:38:55.025274418Z",
"workspaceId": "d7f282d2-b392-4b5c-8cea-05f7523df2d2"
}
]
}
}
}
}
}
},
"x-mint": {
"content": "\n \n\n"
}
},
"post": {
"tags": [
"Organization -- Projects"
],
"summary": "Create Project",
"description": "Creates a new Project within the given Workspace.\n\nA Project is a unit of work where queries, data tables, and semantic catalogs are managed. Projects live inside Workspaces.\n",
"operationId": "createProject_1",
"parameters": [
{
"name": "organizationId",
"in": "path",
"description": "ID of the Organization",
"required": true,
"schema": {
"type": "string"
},
"example": "d0d3c83f-29ed-4f2e-899d-1bfa00eb3cef"
},
{
"name": "workspaceId",
"in": "path",
"description": "ID of the Workspace",
"required": true,
"schema": {
"type": "string"
},
"example": "56d43968-e31d-4010-9b75-018a79a51b17"
}
],
"requestBody": {
"description": "Project to create",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectRequest"
},
"examples": {
"Create Project Example": {
"description": "Create Project Example",
"value": {
"name": "Sample Project Name"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Project created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Project"
},
"examples": {
"Create Project Example": {
"description": "Create Project Example",
"value": {
"id": "URNg0GIj",
"name": "Sample Project Name",
"description": "Non accusantium ducimus accusantium. Laborum eum accusamus sit sit hic eaque doloremque. Occaecati blanditiis facere consequuntur consectetur culpa reiciendis hic tempore dolorem. Saepe impedit nam necessitatibus maxime numquam voluptatum cum. Adipisci mollitia blanditiis sint inventore ex commodi occaecati ipsam quas.",
"domain": "sampleprojectname-cdcn",
"webhookBaseUrl": "https://sampleprojectname-cdcn--test.api.peaka.host",
"createdAt": "2024-09-10T10:11:02.385253956Z",
"workspaceId": "d7f282d2-b392-4b5c-8cea-05f7523df2d2"
}
}
}
}
}
}
},
"x-mint": {
"content": "\n \n\n"
}
}
},
"/organizations/{organizationId}/workspaces/{workspaceId}/projects/{projectId}": {
"get": {
"tags": [
"Organization -- Projects"
],
"summary": "Read Project",
"description": "Returns details of a specified Project.\n\nA Project is a unit of work where queries, data tables, and semantic catalogs are managed. Projects live inside Workspaces.\n",
"operationId": "readProject_1",
"parameters": [
{
"name": "organizationId",
"in": "path",
"description": "ID of the Organization",
"required": true,
"schema": {
"type": "string"
},
"example": "d0d3c83f-29ed-4f2e-899d-1bfa00eb3cef"
},
{
"name": "workspaceId",
"in": "path",
"description": "ID of the Workspace",
"required": true,
"schema": {
"type": "string"
},
"example": "56d43968-e31d-4010-9b75-018a79a51b17"
},
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "SksnYuxH"
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Project"
},
"examples": {
"Read Project Example": {
"description": "Read Project Example",
"value": {
"id": "SksnYuxH",
"name": "Anapp23334",
"description": null,
"domain": "anapp2-rfto",
"webhookBaseUrl": "https://anapp2-rfto--test.api.peaka.host",
"createdAt": "2023-08-21T11:09:04.699714310Z",
"workspaceId": "d7f282d2-b392-4b5c-8cea-05f7523df2d2"
}
}
}
}
}
}
},
"x-mint": {
"content": "\n \n\n"
}
},
"put": {
"tags": [
"Organization -- Projects"
],
"summary": "Update Project",
"description": "Updates the specified Project within a Workspace.\n\nA Project is a unit of work where queries, data tables, and semantic catalogs are managed. Projects live inside Workspaces.\n",
"operationId": "updateProject_1",
"parameters": [
{
"name": "organizationId",
"in": "path",
"description": "ID of the Organization",
"required": true,
"schema": {
"type": "string"
},
"example": "d0d3c83f-29ed-4f2e-899d-1bfa00eb3cef"
},
{
"name": "workspaceId",
"in": "path",
"description": "ID of the Workspace",
"required": true,
"schema": {
"type": "string"
},
"example": "56d43968-e31d-4010-9b75-018a79a51b17"
},
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "SksnYuxH"
}
],
"requestBody": {
"description": "Project to update",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectRequest"
},
"examples": {
"Update Project Example": {
"description": "Update Project Example",
"value": {
"name": "Updated Project Name",
"description": "Iste aut quo maxime dolorem atque. Alias neque porro. Fugiat ipsam similique voluptate quam libero deserunt consequuntur dolorum nobis."
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Project updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Project"
},
"examples": {
"Update Project Example": {
"description": "Update Project Example",
"value": {
"id": "URNg0GIj",
"name": "Updated Project Name",
"description": "Iste aut quo maxime dolorem atque. Alias neque porro. Fugiat ipsam similique voluptate quam libero deserunt consequuntur dolorum nobis.",
"domain": "sampleprojectname-cdcn",
"webhookBaseUrl": null,
"createdAt": "2024-09-10T10:11:02.385253956Z",
"workspaceId": "d7f282d2-b392-4b5c-8cea-05f7523df2d2"
}
}
}
}
}
}
},
"x-mint": {
"content": "\n \n\n"
}
},
"delete": {
"tags": [
"Organization -- Projects"
],
"summary": "Delete Project",
"description": "Deletes the specified Project within a Workspace.\n\nA Project is a unit of work where queries, data tables, and semantic catalogs are managed. Projects live inside Workspaces.\n",
"operationId": "deleteProject_1",
"parameters": [
{
"name": "organizationId",
"in": "path",
"description": "ID of the Organization",
"required": true,
"schema": {
"type": "string"
},
"example": "d0d3c83f-29ed-4f2e-899d-1bfa00eb3cef"
},
{
"name": "workspaceId",
"in": "path",
"description": "ID of the Workspace",
"required": true,
"schema": {
"type": "string"
},
"example": "56d43968-e31d-4010-9b75-018a79a51b17"
},
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "SksnYuxH"
}
],
"responses": {
"200": {
"description": "Project deleted"
}
},
"x-mint": {
"content": "\n \n\n"
}
}
},
"/projects": {
"get": {
"tags": [
"Projects (Deprecated)"
],
"summary": "List Projects",
"description": "Deprecated. Use the List Projects endpoint under Organization instead.\n\nRetrieves all Projects accessible by the authenticated user.\n\nA Project is a unit of work where queries, data tables, and semantic catalogs are managed. Projects live inside Workspaces.\n",
"operationId": "listProjects",
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Project"
}
},
"examples": {
"List of all projects": {
"description": "List of all projects",
"value": [
{
"id": "SksnYuxH",
"name": "Anapp23334",
"description": null,
"domain": "anapp2-rfto",
"webhookBaseUrl": "https://anapp2-rfto--test.api.peaka.host",
"createdAt": "2023-08-21T11:09:04.699714310Z"
},
{
"id": "0IQ6f4QB",
"name": "App Deneme",
"description": null,
"domain": "appdeneme-wmdp",
"webhookBaseUrl": "https://appdeneme-wmdp--test.api.peaka.host",
"createdAt": "2023-12-14T12:38:55.025274418Z"
}
]
}
}
}
}
}
},
"deprecated": true,
"x-mint": {
"content": "\n \n\n"
}
},
"post": {
"tags": [
"Projects (Deprecated)"
],
"summary": "Create Project",
"description": "Deprecated. Use the Create Project endpoint under Organization instead.\n\nCreates a new Project.\n\nA Project is a unit of work where queries, data tables, and semantic catalogs are managed. Projects live inside Workspaces.\n",
"operationId": "createProject",
"requestBody": {
"description": "Project to create",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectRequest"
},
"examples": {
"Create Project Example": {
"description": "Create Project Example",
"value": {
"name": "Sample Project Name"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Project created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Project"
},
"examples": {
"Create Project Example": {
"description": "Create Project Example",
"value": {
"id": "URNg0GIj",
"name": "Sample Project Name",
"description": "Non accusantium ducimus accusantium. Laborum eum accusamus sit sit hic eaque doloremque. Occaecati blanditiis facere consequuntur consectetur culpa reiciendis hic tempore dolorem. Saepe impedit nam necessitatibus maxime numquam voluptatum cum. Adipisci mollitia blanditiis sint inventore ex commodi occaecati ipsam quas.",
"domain": "sampleprojectname-cdcn",
"webhookBaseUrl": "https://sampleprojectname-cdcn--test.api.peaka.host",
"createdAt": "2024-09-10T10:11:02.385253956Z"
}
}
}
}
}
}
},
"deprecated": true,
"x-mint": {
"content": "\n \n\n"
}
}
},
"/projects/{projectId}": {
"get": {
"tags": [
"Projects (Deprecated)"
],
"summary": "Read Project",
"description": "Deprecated. Use the Read Project endpoint under Organization instead.\n\nReturns details of a specified Project.\n\nA Project is a unit of work where queries, data tables, and semantic catalogs are managed. Projects live inside Workspaces.\n",
"operationId": "readProject",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "SksnYuxH"
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Project"
},
"examples": {
"Read Project Example": {
"description": "Read Project Example",
"value": {
"id": "SksnYuxH",
"name": "Anapp23334",
"description": null,
"domain": "anapp2-rfto",
"webhookBaseUrl": "https://anapp2-rfto--test.api.peaka.host",
"createdAt": "2023-08-21T11:09:04.699714310Z"
}
}
}
}
}
}
},
"deprecated": true,
"x-mint": {
"content": "\n \n\n"
}
},
"put": {
"tags": [
"Projects (Deprecated)"
],
"summary": "Update Project",
"description": "Deprecated. Use the Update Project endpoint under Organization instead.\n\nUpdates the specified Project.\n\nA Project is a unit of work where queries, data tables, and semantic catalogs are managed. Projects live inside Workspaces.\n",
"operationId": "updateProject",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "SksnYuxH"
}
],
"requestBody": {
"description": "Project to update",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectRequest"
},
"examples": {
"Update Project Example": {
"description": "Update Project Example",
"value": {
"name": "Updated Project Name",
"description": "Iste aut quo maxime dolorem atque. Alias neque porro. Fugiat ipsam similique voluptate quam libero deserunt consequuntur dolorum nobis."
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Project updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Project"
},
"examples": {
"Update Project Example": {
"description": "Update Project Example",
"value": {
"id": "URNg0GIj",
"name": "Updated Project Name",
"description": "Iste aut quo maxime dolorem atque. Alias neque porro. Fugiat ipsam similique voluptate quam libero deserunt consequuntur dolorum nobis.",
"domain": "sampleprojectname-cdcn",
"webhookBaseUrl": null,
"createdAt": "2024-09-10T10:11:02.385253956Z"
}
}
}
}
}
}
},
"deprecated": true,
"x-mint": {
"content": "\n \n\n"
}
},
"delete": {
"tags": [
"Projects (Deprecated)"
],
"summary": "Delete Project",
"description": "Deprecated. Use the Delete Project endpoint under Organization instead.\n\nDeletes the specified Project.\n\nA Project is a unit of work where queries, data tables, and semantic catalogs are managed. Projects live inside Workspaces.\n",
"operationId": "deleteProject",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "SksnYuxH"
}
],
"responses": {
"200": {
"description": "Project deleted"
}
},
"deprecated": true,
"x-mint": {
"content": "\n \n\n"
}
}
},
"/projects/{projectId}/apiKeys": {
"get": {
"tags": [
"Projects -- Api Key"
],
"summary": "List API Keys",
"description": "Retrieves all API Keys associated with the specified Project.\n",
"operationId": "listApiKeys",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "Project ID",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
}
],
"responses": {
"200": {
"description": "List of API Keys",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiKey"
},
"examples": {
"List API Keys Example": {
"description": "List API Keys Example",
"value": [
{
"name": "test",
"apiKey": null,
"apiKeyId": "21fd1a8d-88d5-4295-b792-5b2113138057"
}
]
}
}
}
}
}
},
"x-mint": {
"content": "\n \n\n"
}
},
"post": {
"tags": [
"Projects -- Api Key"
],
"summary": "Create API Key",
"description": "Creates a new API Key for the specified Project. The API Key is used to authenticate requests to the Peaka API on behalf of the Project.\n\nThe full key value is only returned once at creation time. Store it securely, as it cannot be retrieved later.\n",
"operationId": "createApiKey",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "Project ID",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
}
],
"requestBody": {
"description": "API Key request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiKeyRequest"
},
"examples": {
"API Key Request with Expiration": {
"description": "API Key Request with Expiration",
"value": {
"name": "test",
"expiresAt": "2027-09-10T10:11:00Z"
}
},
"API Key Request With No Expiration": {
"description": "API Key Request With No Expiration",
"value": {
"name": "test"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "API Key created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiKey"
},
"examples": {
"API Key": {
"description": "API Key",
"value": {
"name": "test",
"apiKey": "TtgGcQFq.s3fzROFoop8uHG4pS2LYhoqn1rLb6oW6",
"apiKeyId": "21fd1a8d-88d5-4295-b792-5b2113138057"
}
}
}
}
}
}
},
"x-mint": {
"content": "\n \n\n"
}
}
},
"/projects/{projectId}/apiKeys/{apiKeyId}": {
"delete": {
"tags": [
"Projects -- Api Key"
],
"summary": "Delete API Key",
"description": "Deletes the specified API Key. Once deleted, any requests authenticated with this key will be rejected.\n",
"operationId": "deleteApiKey",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "Project ID",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "apiKeyId",
"in": "path",
"description": "API Key ID",
"required": true,
"schema": {
"type": "string"
},
"example": "21fd1a8d-88d5-4295-b792-5b2113138057"
}
],
"responses": {
"200": {
"description": "API Key deleted"
}
},
"x-mint": {
"content": "\n \n\n"
}
}
},
"/connections/config": {
"get": {
"tags": [
"Connections"
],
"summary": "List Connection Config",
"description": "List all connection configurations.\nThis will return a list of all connection configurations available in the system.",
"operationId": "listConnectionConfig",
"responses": {
"200": {
"description": "List of connection configurations",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConnectionConfiguration"
}
}
}
}
},
"x-mint": {
"content": "\n \n ![](\"https://cdn.peaka.com/badges/project-api-key-badge.png\"/){kind=icon}
\n\n"
}
}
},
"/connections/config/{connectionType}": {
"get": {
"tags": [
"Connections"
],
"summary": "Get Connection Config",
"description": "Returns the configuration schema for a specific connection type, including required credential fields and their types. Use this to understand what parameters are needed when creating a connection of this type.\n",
"operationId": "getConnectionConfig",
"parameters": [
{
"name": "connectionType",
"in": "path",
"description": "Type of connection",
"required": true,
"schema": {
"type": "string"
},
"example": "hubspot"
}
],
"responses": {
"200": {
"description": "Connection configuration",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConnectionConfiguration"
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/connections/{projectId}": {
"get": {
"tags": [
"Connections"
],
"summary": "List Connections",
"description": "Retrieves all connections for the specified Project. A Connection represents an authenticated link to an external data source (e.g., Stripe, Airtable, PostgreSQL).\n",
"operationId": "listConnections",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
}
],
"responses": {
"200": {
"description": "List of Connections",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Connection"
},
"examples": {
"List Connections": {
"description": "Sample List of Connections",
"value": [
{
"id": "c6883de8-78ab-49fb-93c0-70a13652a341",
"name": "Stripe Code2",
"type": "stripe"
},
{
"id": "81e6dfd0-4c88-4e81-a28b-422e89cc07c7",
"name": "airtable",
"type": "airtable"
},
{
"id": "8db17e23-29de-4dab-8886-af9717e0e742",
"name": "airtable2",
"type": "airtable"
},
{
"id": "22706960-023c-411e-a3ac-62d286fa6685",
"name": "exampleAirtableConnection",
"type": "airtable"
}
]
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"post": {
"tags": [
"Connections"
],
"summary": "Create Connection",
"description": "This endpoint allows you to create a new connection for a specified project.\n\nYou need to provide the project ID and the connection details in the request body.\n\nThe connection details include the name, type, and credentials required for the connection.\n\nDepending on the connection type, additional parameters may be required under credentials.\n\nYou can view the list of supported connection types by calling the /connections/config endpoint.\n\nYou can switch examples from the second dropdown of the sample request component. (cURL (first dropdown) - Stripe Connection Request (second dropdown))\n\n**Note**: Typically, the connection creation process involves the following steps:\n1. First, learn about the connection type and the required parameters by calling the /connections/config endpoint.\n2. Create a connection request with the required parameters.\n3. If the connection requires Oauth2 authorization, there may be additional steps to follow. See https://docs.peaka.com/how-to-guides/how-to-create-oauth2-based-connections-via-peaka for more information.\n\n**Example**:\n- POSTGRES Connection Configuration:\n\nGET /connections/config endpoint displays all of the connection types.\n\nGET /connection/config/POSTGRES endpoint displays the POSTGRES connection configuration.\n\nThe definition of the POSTGRES connection configuration is as follows:\n``` json\n {\n \"connectionType\": \"POSTGRES\",\n \"connectionTypeLabel\": \"PostgreSQL\",\n \"name\": \"PostgreSQL\",\n \"authorizationType\": \"custom\",\n \"credentialSchemaType\": \"postgres_credential_schema\",\n \"category\": \"Database\",\n \"configuration\": [\n {\n \"fieldName\": \"url\",\n \"fieldType\": \"text\",\n \"required\": true,\n \"description\": \"URL\"\n },\n {\n \"fieldName\": \"port\",\n \"fieldType\": \"number\",\n \"required\": true,\n \"description\": \"Port\"\n },\n {\n \"fieldName\": \"user\",\n \"fieldType\": \"text\",\n \"required\": true,\n \"description\": \"User\"\n },\n {\n \"fieldName\": \"password\",\n \"fieldType\": \"text\",\n \"required\": true,\n \"description\": \"Password\"\n },\n {\n \"fieldName\": \"databaseName\",\n \"fieldType\": \"text\",\n \"required\": true,\n \"description\": \"Database Name\"\n },\n {\n \"fieldName\": \"useSsl\",\n \"fieldType\": \"boolean\",\n \"required\": true,\n \"description\": \"Use SSL\"\n }\n ],\n \"documentationUrl\": \"https://docs.peaka.com/integrations/postgresql\"\n }\n```\n\nAccording to the POSTGRES connection configuration, the connection request should include the following parameters (respecting to the required flag):\n- url: URL of the host IP or domain\n- port: Port number\n- user: User of the database\n- password: Password of the user\n- databaseName: Name of the database\n- useSsl: Boolean value to indicate whether to use SSL\n\n``` json\n{\n \"name\": \"examplePostgre\",\n \"type\": \"POSTGRES\",\n \"credential\": {\n \"url\": \"\n \n\n"
}
}
},
"/connections/{projectId}/oauth2": {
"post": {
"tags": [
"Connections"
],
"summary": "Oauth2 Callback",
"description": "This callback/webhook is used while creating a new connection with Oauth2. See https://docs.peaka.com/how-to-guides/how-to-create-oauth2-based-connections-via-peaka for more information.",
"operationId": "oauth2Callback",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
}
],
"requestBody": {
"description": "Oauth2 Callback Body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Oauth2Callback"
},
"examples": {
"Oauth2 Callback Request": {
"description": "Oauth2 Callback Request",
"value": {
"queryParameters": "code=1234&state=xyz¶m1=value1¶m2=value2"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Connection created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Connection"
},
"examples": {
"Successful Oauth2 Connection": {
"description": "Sample Google Analytics Connection",
"value": {
"id": "6243f42a-42d0-4821-a90f-763cda6cda50",
"name": "exampleOauth2Connection",
"type": "google_analytics"
}
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/connections/{projectId}/{connectionId}": {
"get": {
"tags": [
"Connections"
],
"summary": "Get Connection",
"description": "Returns details of a specified Connection.\n",
"operationId": "getConnection",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "connectionId",
"in": "path",
"description": "ID of the connection",
"required": true,
"schema": {
"type": "string"
},
"example": "8db17e23-29de-4dab-8886-af9717e0e742"
}
],
"responses": {
"200": {
"description": "Get Connection by ID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Connection"
},
"examples": {
"Airtable Connection": {
"description": "Sample Airtable Connection",
"value": {
"id": "8db17e23-29de-4dab-8886-af9717e0e742",
"name": "airtable2",
"type": "airtable"
}
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"put": {
"tags": [
"Connections"
],
"summary": "Update Connection",
"description": "Updates the specified Connection. You can modify the name, credentials, or other parameters. The request body follows the same structure as the Create Connection endpoint.\n",
"operationId": "updateConnection",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "connectionId",
"in": "path",
"description": "ID of the connection",
"required": true,
"schema": {
"type": "string"
},
"example": "8db17e23-29de-4dab-8886-af9717e0e742"
}
],
"requestBody": {
"description": "Connection Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConnectionRequest"
},
"examples": {
"HubSpot Connection Request with Oauth": {
"description": "Sample HubSpot Connection parameters",
"value": {
"name": "exampleHubspotConnection",
"type": "hubspot",
"credential": {
"clientId": "15d6b8c5-48ea-4955-8ce5-d04bb9adad25",
"clientSecret": "64d70b56-ae19-4fee-9fa2-3e9113bcb202",
"refreshToken": "eu1-eae3-1af4-583d-91d4-f6414699feea"
}
}
},
"Stripe Connection Request": {
"description": "Sample Stripe Connection parameters",
"value": {
"name": "exampleStripeConnection21",
"type": "stripe",
"credential": {
"token": "\n \n\n"
}
},
"delete": {
"tags": [
"Connections"
],
"summary": "Delete Connection",
"description": "Deletes the specified Connection. Any catalogs using this connection will lose access to their data source.\n",
"operationId": "deleteConnection",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "connectionId",
"in": "path",
"description": "ID of the connection",
"required": true,
"schema": {
"type": "string"
},
"example": "8db17e23-29de-4dab-8886-af9717e0e742"
}
],
"responses": {
"200": {
"description": "Connection deleted successfully"
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/connections/{projectId}/{connectionId}/detail": {
"get": {
"tags": [
"Connections"
],
"summary": "Get Connection Detail",
"description": "Get connection detail by ID. Returns only non-sensitive information.",
"operationId": "getConnectionView",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "connectionId",
"in": "path",
"description": "ID of the connection",
"required": true,
"schema": {
"type": "string"
},
"example": "8db17e23-29de-4dab-8886-af9717e0e742"
}
],
"responses": {
"200": {
"description": "Connection Detail",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"description": "Credential object for the connection.\n\n Its structure is dependent on the connection type and can be fetched by following url: /connections/config"
},
"examples": {
"Connection Detail": {
"description": "Sample Bullhorn Connection parameters",
"value": {
"type": "bullhorn",
"restApiTokenUrl": "http://a.b.c",
"swimlane": "123",
"corpToken": "123"
}
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/catalogs": {
"get": {
"tags": [
"Data -- Catalogs"
],
"summary": "List Catalogs",
"description": "Returns all catalogs registered in the specified project. Each catalog represents a data source connected to Peaka, such as Airtable, Stripe, or an internal Peaka storage. Built-in catalog types like `internal` (Peaka Tables and BI Tables) and `query` (Peaka Queries) are always present.",
"operationId": "listCatalogs",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Catalog"
}
},
"examples": {
"List Catalogs": {
"description": "List Catalogs",
"value": [
{
"id": "1",
"name": "peaka",
"displayName": "Peaka",
"catalogType": "internal",
"connectionId": null
},
{
"id": "2",
"name": "peaka",
"displayName": "Peaka Query",
"catalogType": "query",
"connectionId": null
},
{
"id": "555414570395501064",
"name": "examplename34",
"displayName": "exampleName34",
"catalogType": "stripe",
"connectionId": "fe47b030-3718-4537-a6ba-eaa93c7204ee"
},
{
"id": "555611268656923356",
"name": "examplename35",
"displayName": "exampleName35",
"catalogType": "segment",
"connectionId": "fe47b030-3718-4537-a6ba-eaa93c7204ee"
},
{
"id": "625151643029078208",
"name": "exampleairtablecatalog2",
"displayName": "exampleAirtableCatalog2",
"catalogType": "airtable",
"connectionId": "8db17e23-29de-4dab-8886-af9717e0e742"
}
]
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"post": {
"tags": [
"Data -- Catalogs"
],
"summary": "Create Catalog",
"description": "Creates a new catalog in the specified project. A catalog represents a connected data source — such as Airtable, Stripe, or Google Sheets — that exposes its schemas and tables for querying within Peaka. Requires a `name` and a `connectionId` referencing an existing connection. Some connectors accept additional `extraParameters` (e.g., Google Sheets requires specifying which sheets to include).",
"operationId": "createCatalog",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
}
],
"requestBody": {
"description": "Catalog Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CatalogRequest"
},
"examples": {
"Create Airtable Catalog": {
"description": "Create Airtable Catalog",
"value": {
"name": "exampleAirtableCatalog",
"connectionId": "8db17e23-29de-4dab-8886-af9717e0e742"
}
},
"Create GoogleSheets Catalog": {
"description": "Create GoogleSheets Catalog",
"value": {
"name": "exampleGoogleSheetsCatalog",
"connectionId": "p3fb17l83-g9de-46mb-8823-yu9717e0ekl8",
"extraParameters": {
"sheets": [
{
"id": "1zBlTlAarZ94Z-xbo8T-GZEckV93VGSse7qq0_S0Kdzc",
"name": "Customers"
},
{
"id": "glkuldqwerqwAarZ94Z-xbo8T-GdfhsdgVGSse7qq0_S0Kdzc",
"name": "Sales"
}
]
}
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Catalog created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Catalog"
},
"examples": {
"Create Airtable Catalog": {
"description": "Create Airtable Catalog",
"value": {
"id": "626654862255325504",
"name": "exampleairtablecatalog",
"displayName": "exampleAirtableCatalog",
"catalogType": "airtable",
"connectionId": "8db17e23-29de-4dab-8886-af9717e0e742"
}
},
"Create Stripe Catalog": {
"description": "Create Stripe Catalog",
"value": {
"id": "626654862255325504",
"name": "exampleStripeCatalog",
"displayName": "exampleStripeCatalog",
"catalogType": "stripe",
"connectionId": "8db17e23-29de-4dab-8886-af9717e0e742"
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "string"
},
"examples": {
"Bad Request": {
"description": "Bad Request",
"value": {
"errorCode": 100,
"message": "There are already a catalog with same name!!"
}
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/catalogs/{catalogId}": {
"get": {
"tags": [
"Data -- Catalogs"
],
"summary": "Read Catalog",
"description": "Retrieves the details of a single catalog by its ID. Returns the catalog's name, display name, catalog type, and the associated connection ID.",
"operationId": "readCatalog",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "catalogId",
"in": "path",
"description": "ID of the catalog",
"required": true,
"schema": {
"type": "string"
},
"example": 846085284821991600
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Catalog"
},
"examples": {
"Read Catalog": {
"description": "Read Catalog",
"value": {
"id": "627249916703408649",
"name": "exampleairtablecatalog",
"displayName": "exampleAirtableCatalog",
"catalogType": "airtable",
"connectionId": "8db17e23-29de-4dab-8886-af9717e0e74311"
}
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"delete": {
"tags": [
"Data -- Catalogs"
],
"summary": "Delete Catalog",
"description": "Permanently removes the specified catalog from the project. This disconnects the underlying data source and makes all its schemas and tables unavailable for querying. This action is irreversible.",
"operationId": "deleteCatalog",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "catalogId",
"in": "path",
"description": "ID of the catalog",
"required": true,
"schema": {
"type": "string"
},
"example": 846085284821991600
}
],
"responses": {
"200": {
"description": "Catalog deleted successfully"
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/catalogs/{catalogId}/schemas": {
"get": {
"tags": [
"Data -- Catalogs"
],
"summary": "List Schemas",
"description": "Returns all schemas available under the specified catalog. Schemas are logical groupings of tables within a catalog. For external connectors, schemas typically correspond to databases or namespaces exposed by the data source.",
"operationId": "listSchemas",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "catalogId",
"in": "path",
"description": "ID of the catalog",
"required": true,
"schema": {
"type": "string"
},
"example": 846085284821991600
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Schema"
}
},
"examples": {
"List Schemas": {
"description": "List Schemas",
"value": [
{
"catalogId": "544639856899260964",
"schemaName": "testSchema"
}
]
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/catalogs/{catalogId}/schemas/{schemaName}/tables": {
"get": {
"tags": [
"Data -- Catalogs"
],
"summary": "List Tables",
"description": "Lists all tables available under the specified schema of a catalog. Each table entry includes its catalog and schema context along with caching metadata (`isCacheable`, `isDynamicTable`, `isCached`, `supportedCacheTypes`). `supportedCacheTypes` lists the cache types (`FULL_REFRESH`, `INCREMENTAL`) that can be used when creating a cache for the table; it is empty when the table is not cacheable, and absent when capability information could not be resolved. For the internal catalog, this includes [Peaka Tables](https://docs.peaka.com/connecting-your-data/peaka-table) and [Peaka BI Tables](https://docs.peaka.com/connecting-your-data/peaka-big-table).",
"operationId": "listTables_1",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "catalogId",
"in": "path",
"description": "ID of the catalog",
"required": true,
"schema": {
"type": "string"
},
"example": 846085284821991600
},
{
"name": "schemaName",
"in": "path",
"description": "Name of the schema",
"required": true,
"schema": {
"type": "string"
},
"example": "public"
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Table"
}
},
"examples": {
"List Tables": {
"description": "List Tables",
"value": [
{
"catalogId": "544639856899260964",
"catalogName": "hubspot",
"schemaName": "crm",
"tableName": "companies",
"isCacheable": true,
"isDynamicTable": false,
"isCached": false,
"supportedCacheTypes": [
"FULL_REFRESH",
"INCREMENTAL"
]
},
{
"catalogId": "544639856899260964",
"catalogName": "hubspot",
"schemaName": "crm",
"tableName": "owners",
"isCacheable": false,
"isDynamicTable": false,
"isCached": false,
"supportedCacheTypes": []
}
]
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/catalogs/{catalogId}/schemas/{schemaName}/tables/{tableName}/columns": {
"get": {
"tags": [
"Data -- Catalogs"
],
"summary": "List Columns",
"description": "Lists all columns for a specific table within a catalog. Returns full column metadata including name, data type, display name, default value, and constraints (nullability, uniqueness). Some connectors expose additional virtual columns (prefixed with `_q_`) that can be used to pass query-time parameters to the data source.",
"operationId": "listColumns_1",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "catalogId",
"in": "path",
"description": "ID of the catalog",
"required": true,
"schema": {
"type": "string"
},
"example": 846085284821991600
},
{
"name": "schemaName",
"in": "path",
"description": "Name of the schema",
"required": true,
"schema": {
"type": "string"
},
"example": "public"
},
{
"name": "tableName",
"in": "path",
"description": "Name of the table",
"required": true,
"schema": {
"type": "string"
},
"example": "actor"
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ColumnDetail"
}
},
"examples": {
"List Columns": {
"description": "List Columns",
"value": [
{
"name": "id",
"dataType": "bigint",
"displayName": "id",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "hs_object_id",
"dataType": "varchar",
"displayName": "hs_object_id",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "email",
"dataType": "varchar",
"displayName": "email",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "name",
"dataType": "varchar",
"displayName": "name",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "domain",
"dataType": "varchar",
"displayName": "domain",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "industry",
"dataType": "varchar",
"displayName": "industry",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "phone",
"dataType": "varchar",
"displayName": "phone",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "country",
"dataType": "varchar",
"displayName": "country",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "state",
"dataType": "varchar",
"displayName": "state",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "city",
"dataType": "varchar",
"displayName": "city",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "description",
"dataType": "varchar",
"displayName": "description",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "createdate",
"dataType": "timestamp(6)",
"displayName": "createdate",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "hs_lastmodifieddate",
"dataType": "timestamp(6)",
"displayName": "hs_lastmodifieddate",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "properties",
"dataType": "json",
"displayName": "properties",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "propertieswithhistory",
"dataType": "json",
"displayName": "propertieswithhistory",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "createdat",
"dataType": "timestamp(6)",
"displayName": "createdat",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "updatedat",
"dataType": "timestamp(6)",
"displayName": "updatedat",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "archived",
"dataType": "boolean",
"displayName": "archived",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "archivedat",
"dataType": "timestamp(6)",
"displayName": "archivedat",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "associations",
"dataType": "json",
"displayName": "associations",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "_q_pagination_anchor",
"dataType": "varchar",
"displayName": "_q_pagination_anchor",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "_q_limit",
"dataType": "bigint",
"displayName": "_q_limit",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "_q_offset",
"dataType": "varchar",
"displayName": "_q_offset",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "_q_properties",
"dataType": "json",
"displayName": "_q_properties",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "_q_properties_with_history",
"dataType": "varchar",
"displayName": "_q_properties_with_history",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "_q_associations",
"dataType": "varchar",
"displayName": "_q_associations",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "_q_archived",
"dataType": "boolean",
"displayName": "_q_archived",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
}
]
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/catalogs/{catalogId}/schemas/{schemaName}/tables/{tableName}/isCached": {
"get": {
"tags": [
"Data -- Catalogs"
],
"summary": "Table is Cached",
"description": "Checks whether the specified table has an active cache in Peaka. When a table is cached, its data is stored locally in Peaka, enabling significantly faster query performance compared to live queries against the original data source. Returns `isCached: true` if a cache is currently active, or `false` otherwise.\n\nThe response also carries `isCacheable` and `supportedCacheTypes` (`FULL_REFRESH`, `INCREMENTAL`), so a single call is enough to decide whether — and with which schedule types — a cache can be created for the table. `supportedCacheTypes` is empty when the table is not cacheable; both fields are absent when the information could not be resolved.",
"operationId": "isCached",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "catalogId",
"in": "path",
"description": "ID of the catalog",
"required": true,
"schema": {
"type": "string"
},
"example": 846085284821991600
},
{
"name": "schemaName",
"in": "path",
"description": "Name of the schema",
"required": true,
"schema": {
"type": "string"
},
"example": "public"
},
{
"name": "tableName",
"in": "path",
"description": "Name of the table",
"required": true,
"schema": {
"type": "string"
},
"example": "actor"
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TableCacheResult"
},
"examples": {
"Table is Cached": {
"description": "Table is Cached",
"value": {
"isCached": true,
"isCacheable": true,
"supportedCacheTypes": [
"FULL_REFRESH",
"INCREMENTAL"
]
}
},
"Table is Not Cacheable": {
"description": "Table is Not Cacheable",
"value": {
"isCached": false,
"isCacheable": false,
"supportedCacheTypes": []
}
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/catalogs/{catalogId}/schemas/{schemaName}/tables/{tableName}/statistics": {
"get": {
"tags": [
"Data -- Catalogs"
],
"summary": "Table Statistics",
"description": "Returns statistical metadata for the specified table. Includes per-column `distinctFraction` values, which represent the estimated fraction of distinct values in a column relative to the total row count. These statistics are used internally by Peaka's query optimizer to improve query planning and execution performance.",
"operationId": "getTableStatistics",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "catalogId",
"in": "path",
"description": "ID of the catalog",
"required": true,
"schema": {
"type": "string"
},
"example": 846085284821991600
},
{
"name": "schemaName",
"in": "path",
"description": "Name of the schema",
"required": true,
"schema": {
"type": "string"
},
"example": "public"
},
{
"name": "tableName",
"in": "path",
"description": "Name of the table",
"required": true,
"schema": {
"type": "string"
},
"example": "actor"
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TableStatistics"
},
"examples": {
"Table Statistics": {
"description": "Table Statistics",
"value": {
"catalogId": "846085284821991568",
"schemaName": "public",
"tableName": "actor",
"columnStatistics": [
{
"columnName": "actor_id",
"distinctFraction": -1
},
{
"columnName": "first_name",
"distinctFraction": -0.64
},
{
"columnName": "last_name",
"distinctFraction": -0.605
},
{
"columnName": "last_update",
"distinctFraction": 1
}
]
}
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/catalogs/{catalogId}/share": {
"post": {
"tags": [
"Data -- Catalogs"
],
"summary": "Share Catalog",
"description": "Shares a catalog from the current project with another Peaka project. The target project gains read access to the catalog's schemas and tables. Provide the `targetProjectId` of the project you want to share the catalog with.",
"operationId": "shareCatalog",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "catalogId",
"in": "path",
"description": "ID of the catalog",
"required": true,
"schema": {
"type": "string"
},
"example": 846085284821991600
}
],
"requestBody": {
"description": "Share Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CatalogShareRequestV2"
},
"example": {
"targetProjectId": "MQtMNNBY"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Catalog shared successfully",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/SharedCatalogResponse"
},
"examples": {
"Share Catalog Response": {
"description": "Share Catalog Response",
"value": {
"sharedCatalogId": "555611268656923356"
}
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/search": {
"post": {
"tags": [
"Data -- Catalogs"
],
"summary": "Search",
"description": "Search for catalogs, schemas, and tables across the project. You can filter the search results by specifying a catalog or schema. You can also specify a limit and offset for pagination.\n\n\nSee the request body for more details.\n",
"operationId": "search",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
}
],
"requestBody": {
"description": "Search Anywhere",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
},
"examples": {
"Search Anywhere Request": {
"description": "Search Anywhere Request",
"value": {
"query": "apple"
}
},
"Search Under a Catalog": {
"description": "Search Under a Catalog",
"value": {
"query": "apple",
"catalog": "my_catalog"
}
},
"Search Under a Schema": {
"description": "Search Under a Schema",
"value": {
"query": "apple",
"catalog": "my_catalog",
"schema": "my_schema"
}
},
"Search with Limit Increased": {
"description": "Search with Limit Increased",
"value": {
"query": "apple",
"limit": 200
}
},
"Search with Offset": {
"description": "Search with Offset",
"value": {
"query": "apple",
"limit": 200,
"offset": 400
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Search",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResult"
},
"examples": {
"Search Result": {
"description": "Search Result",
"value": {
"matchedCatalogs": [
{
"catalog": "apple_catalog"
}
],
"matchedSchemas": [
{
"catalog": "my_catalog",
"schema": "apple_schema"
}
],
"matchedTables": [
{
"catalog": "my_catalog",
"schema": "apple_schema",
"table": "apple_table"
},
{
"catalog": "my_catalog",
"schema": "another_schema",
"table": "another_apple_table"
}
],
"meta": {
"page": {
"limit": 100,
"offset": 0,
"nextOffset": null
},
"query": {
"text": "apple"
}
}
}
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/bitable": {
"get": {
"tags": [
"Data -- Internal Tables"
],
"summary": "List BI Tables",
"description": "Lists all [Peaka BI Tables](https://docs.peaka.com/connecting-your-data/peaka-bi-table) in the project. Peaka BI Table is a robust data management solution optimized for handling large datasets of over one million records. It uses a column-oriented data storage approach, resulting in exceptionally fast filtering and grouping performance without requiring additional indexing. It is particularly well-suited for event data and bulk insertions, though it does not support JSON data types. See also: [Differences of Peaka Table and Peaka BI Table](https://docs.peaka.com/connecting-your-data/differences-of-peaka-table-and-peaka-bi-table)",
"operationId": "listBiTables",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Table"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/bitable/{tableName}": {
"post": {
"tags": [
"Data -- Internal Tables"
],
"summary": "Create BI Table",
"description": "Creates a new [Peaka BI Table](https://docs.peaka.com/connecting-your-data/peaka-bi-table) with the given name in the specified project. Peaka BI Table uses a column-oriented storage approach optimized for large datasets of over one million records, offering fast filtering and grouping performance without additional indexing. It is particularly well-suited for event data and bulk insertions. Note that JSON data type is not supported. See also: [Differences of Peaka Table and Peaka BI Table](https://docs.peaka.com/connecting-your-data/differences-of-peaka-table-and-peaka-bi-table)",
"operationId": "createInternalBiTable",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "tableName",
"in": "path",
"description": "Name of the BI table to create",
"required": true,
"schema": {
"type": "string"
},
"example": "events"
}
],
"responses": {
"200": {
"description": "Table created successfully",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/Table"
},
"example": {
"catalogId": "1",
"catalogName": "peaka",
"schemaName": "bitable",
"tableName": "testtable",
"isCacheable": false,
"isDynamicTable": false,
"isCached": false
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"delete": {
"tags": [
"Data -- Internal Tables"
],
"summary": "Delete BI Table",
"description": "Permanently deletes the specified [Peaka BI Table](https://docs.peaka.com/connecting-your-data/peaka-bi-table) and all its data from the project. This action is irreversible — all rows, columns, and schema definitions associated with the BI Table will be removed.",
"operationId": "deleteBiTable",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "tableName",
"in": "path",
"description": "Name of the BI table to delete",
"required": true,
"schema": {
"type": "string"
},
"example": "events"
}
],
"responses": {
"200": {
"description": "Table deleted successfully"
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/bitable/{tableName}/columns": {
"get": {
"tags": [
"Data -- Internal Tables"
],
"summary": "List BI Columns",
"description": "Lists all columns defined in the specified [Peaka BI Table](https://docs.peaka.com/connecting-your-data/peaka-bi-table). Returns column metadata including name, data type, display name, default value, and constraints such as nullability and uniqueness. Note that Peaka BI Table does not support JSON data types.",
"operationId": "listBiColumns",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "tableName",
"in": "path",
"description": "Name of the BI table",
"required": true,
"schema": {
"type": "string"
},
"example": "events"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ColumnDetail"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"post": {
"tags": [
"Data -- Internal Tables"
],
"summary": "Add BI Column",
"description": "Adds one or more columns to the specified [Peaka BI Table](https://docs.peaka.com/connecting-your-data/peaka-bi-table). Each column definition includes its name, data type, display name, optional default value, and constraints (nullability, uniqueness). Peaka BI Table supports VARCHAR, BIGINT, BOOLEAN, TIMESTAMP, TIME, DATE, UUID, and DECIMAL data types. Note that JSON data type is not supported in Peaka BI Table.",
"operationId": "addBiColumn",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "tableName",
"in": "path",
"description": "Name of the BI table",
"required": true,
"schema": {
"type": "string"
},
"example": "events"
}
],
"requestBody": {
"description": "Column Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ColumnRequest"
},
"examples": {
"Add Column": {
"description": "Add Column",
"value": [
{
"name": "varcharcol",
"dataType": "VARCHAR",
"displayName": "varcharcol",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "bigintcol",
"dataType": "BIGINT",
"displayName": "bigintcol",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "booleancol",
"dataType": "BOOLEAN",
"displayName": "booleancol",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "timestampcol",
"dataType": "TIMESTAMP",
"displayName": "timestampcol",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "timecol",
"dataType": "TIME",
"displayName": "timecol",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "datecol",
"dataType": "DATE",
"displayName": "datecol",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "uuidcol",
"dataType": "UUID",
"displayName": "uuidcol",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "decimalcol",
"dataType": "DECIMAL",
"displayName": "decimalcol",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
}
]
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Column added successfully",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/ColumnDetail"
},
"example": [
{
"name": "num19",
"dataType": "bigint",
"displayName": "num19",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "num18",
"dataType": "bigint",
"displayName": "num18",
"defaultValue": "3",
"isNotNull": false,
"isUnique": true
}
]
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/bitable/{tableName}/columns/{columnName}": {
"put": {
"tags": [
"Data -- Internal Tables"
],
"summary": "Update BI Column",
"description": "Updates the definition of an existing column in the specified [Peaka BI Table](https://docs.peaka.com/connecting-your-data/peaka-bi-table). Allows modifying the column's name, display name, data type, default value, and constraints such as nullability and uniqueness.",
"operationId": "updateBiColumn",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "tableName",
"in": "path",
"description": "Name of the BI table",
"required": true,
"schema": {
"type": "string"
},
"example": "events"
},
{
"name": "columnName",
"in": "path",
"description": "Name of the column to update",
"required": true,
"schema": {
"type": "string"
},
"example": "event_type"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ColumnRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ColumnDetail"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"delete": {
"tags": [
"Data -- Internal Tables"
],
"summary": "Delete BI Column",
"description": "Permanently removes a column from the specified [Peaka BI Table](https://docs.peaka.com/connecting-your-data/peaka-bi-table). This action is irreversible — the column and all its stored data will be deleted from the BI Table.",
"operationId": "deleteBiColumn",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "tableName",
"in": "path",
"description": "Name of the BI table",
"required": true,
"schema": {
"type": "string"
},
"example": "events"
},
{
"name": "columnName",
"in": "path",
"description": "Name of the column to delete",
"required": true,
"schema": {
"type": "string"
},
"example": "event_type"
}
],
"responses": {
"200": {
"description": "Column deleted successfully"
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/table": {
"get": {
"tags": [
"Data -- Internal Tables"
],
"summary": "List Tables",
"description": "Lists all [Peaka Tables](https://docs.peaka.com/connecting-your-data/peaka-table) in the project. Peaka Table is an internal relational database within Peaka that allows you to organize and manage data efficiently. It supports structured data storage and enables you to add, delete, filter, and edit your data, including JSON data types. It is best suited for smaller datasets requiring frequent edits and broader data type support. See also: [Differences of Peaka Table and Peaka BI Table](https://docs.peaka.com/connecting-your-data/differences-of-peaka-table-and-peaka-bi-table)",
"operationId": "listTables",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Table"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/table/{tableName}": {
"post": {
"tags": [
"Data -- Internal Tables"
],
"summary": "Create Table",
"description": "Creates a new [Peaka Table](https://docs.peaka.com/connecting-your-data/peaka-table) with the given name in the specified project. Peaka Table is an internal relational database within Peaka that supports structured data storage with full CRUD operations. It accommodates a wide range of data types including JSON, and is best suited for smaller datasets that require frequent edits and precise changes. See also: [Differences of Peaka Table and Peaka BI Table](https://docs.peaka.com/connecting-your-data/differences-of-peaka-table-and-peaka-bi-table)",
"operationId": "createInternalTable",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "tableName",
"in": "path",
"description": "Name of the table to create",
"required": true,
"schema": {
"type": "string"
},
"example": "customers"
}
],
"responses": {
"200": {
"description": "Table created successfully",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/Table"
},
"example": {
"catalogId": "1",
"catalogName": "peaka",
"schemaName": "table",
"tableName": "testtable",
"isCacheable": false,
"isDynamicTable": false,
"isCached": false
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"delete": {
"tags": [
"Data -- Internal Tables"
],
"summary": "Delete Table",
"description": "Permanently deletes the specified [Peaka Table](https://docs.peaka.com/connecting-your-data/peaka-table) and all its data from the project. This action is irreversible — all rows, columns, and schema definitions associated with the table will be removed.",
"operationId": "deleteTable",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "tableName",
"in": "path",
"description": "Name of the table to delete",
"required": true,
"schema": {
"type": "string"
},
"example": "customers"
}
],
"responses": {
"200": {
"description": "Table deleted successfully"
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/table/{tableName}/columns": {
"get": {
"tags": [
"Data -- Internal Tables"
],
"summary": "List Columns",
"description": "Lists all columns defined in the specified [Peaka Table](https://docs.peaka.com/connecting-your-data/peaka-table). Returns column metadata including name, data type, display name, default value, and constraints such as nullability and uniqueness.",
"operationId": "listColumns",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "tableName",
"in": "path",
"description": "Name of the table",
"required": true,
"schema": {
"type": "string"
},
"example": "customers"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ColumnDetail"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"post": {
"tags": [
"Data -- Internal Tables"
],
"summary": "Add Column",
"description": "Adds one or more columns to the specified [Peaka Table](https://docs.peaka.com/connecting-your-data/peaka-table). Each column definition includes its name, data type, display name, optional default value, and constraints (nullability, uniqueness). Peaka Table supports a wide range of data types including VARCHAR, BIGINT, BOOLEAN, TIMESTAMP, TIME, DATE, UUID, DECIMAL, and JSON.",
"operationId": "addColumn",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "tableName",
"in": "path",
"description": "Name of the table",
"required": true,
"schema": {
"type": "string"
},
"example": "customers"
}
],
"requestBody": {
"description": "Column Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ColumnRequest"
},
"examples": {
"Add Column": {
"description": "Add Column",
"value": [
{
"name": "varcharcol",
"dataType": "VARCHAR",
"displayName": "varcharcol",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "bigintcol",
"dataType": "BIGINT",
"displayName": "bigintcol",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "booleancol",
"dataType": "BOOLEAN",
"displayName": "booleancol",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "timestampcol",
"dataType": "TIMESTAMP",
"displayName": "timestampcol",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "timecol",
"dataType": "TIME",
"displayName": "timecol",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "datecol",
"dataType": "DATE",
"displayName": "datecol",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "uuidcol",
"dataType": "UUID",
"displayName": "uuidcol",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "decimalcol",
"dataType": "DECIMAL",
"displayName": "decimalcol",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
}
]
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Column added successfully",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/ColumnDetail"
},
"example": [
{
"name": "num19",
"dataType": "bigint",
"displayName": "num19",
"defaultValue": null,
"isNotNull": false,
"isUnique": false
},
{
"name": "num18",
"dataType": "bigint",
"displayName": "num18",
"defaultValue": "3",
"isNotNull": false,
"isUnique": true
}
]
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/table/{tableName}/columns/{columnName}": {
"put": {
"tags": [
"Data -- Internal Tables"
],
"summary": "Update Column",
"description": "Updates the definition of an existing column in the specified [Peaka Table](https://docs.peaka.com/connecting-your-data/peaka-table). Allows modifying the column's name, display name, data type, default value, and constraints such as nullability and uniqueness.",
"operationId": "updateColumn",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "tableName",
"in": "path",
"description": "Name of the table",
"required": true,
"schema": {
"type": "string"
},
"example": "customers"
},
{
"name": "columnName",
"in": "path",
"description": "Name of the column to update",
"required": true,
"schema": {
"type": "string"
},
"example": "email"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ColumnRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ColumnDetail"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"delete": {
"tags": [
"Data -- Internal Tables"
],
"summary": "Delete Column",
"description": "Permanently removes a column from the specified [Peaka Table](https://docs.peaka.com/connecting-your-data/peaka-table). This action is irreversible — the column and all its stored data will be deleted from the table.",
"operationId": "deleteColumn",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "tableName",
"in": "path",
"description": "Name of the table",
"required": true,
"schema": {
"type": "string"
},
"example": "customers"
},
{
"name": "columnName",
"in": "path",
"description": "Name of the column to delete",
"required": true,
"schema": {
"type": "string"
},
"example": "email"
}
],
"responses": {
"200": {
"description": "Column deleted successfully"
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/table/{tableName}/import": {
"post": {
"tags": [
"Data -- Internal Tables"
],
"summary": "Import CSV",
"description": "Imports data from a CSV file into a specified internal table in a given project.\n\nThis endpoint accepts a `multipart/form-data` request with two parts:\n\n- **file**: The CSV file to be imported.\n- **request**: A JSON string describing how the CSV columns map to the table's columns.\n\nCSV file format can be get from `/projects/{projectId}/table/{tableName}/sample`.\n\n\n#### Request JSON syntax\nThe `request` part must contain:\n- `mappings`: A list of objects, each with:\n - `name`: The name of the target column in the internal table.\n - Either `csvColumnName` or `csvColumnIndex` to define the corresponding column in the CSV.\n- `containsHeader`: A boolean indicating whether the CSV includes a header row.\n\n#### Examples\nWith column names:\n```\n{\n \"mappings\": [\n { \"name\": \"numcol\", \"csvColumnName\": \"numcol\" },\n { \"name\": \"text\", \"csvColumnName\": \"text\" },\n { \"name\": \"decimalcol\", \"csvColumnName\": \"decimalcol\" }\n ],\n \"containsHeader\": true\n}\n```\n\nWith column indexes:\n```\n{\n \"mappings\": [\n { \"name\": \"numcol\", \"csvColumnIndex\": 0 },\n { \"name\": \"text\", \"csvColumnIndex\": 1 },\n { \"name\": \"decimalcol\", \"csvColumnIndex\": 2 }\n ],\n \"containsHeader\": false\n}\n```\n\n- When the CSV contains a header row (`containsHeader: true`), you can use either `csvColumnName` or `csvColumnIndex`.\n- When the CSV does **not** contain a header row (`containsHeader: false`), you **must** use `csvColumnIndex`.\n\n#### Response\nThe endpoint currently runs synchronously and returns an `ImportJob` object with the job status and number of processed rows.\n\nIn future versions, this endpoint will return only the `jobId`, and the progress/result will be tracked via a separate job status endpoint:\n`GET /jobs/{id}`\n",
"operationId": "importCsv",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "tableName",
"in": "path",
"description": "Name of the table to import into",
"required": true,
"schema": {
"type": "string"
},
"example": "customers"
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"required": [
"file",
"request"
],
"type": "object",
"properties": {
"file": {
"type": "string",
"description": "CSV file",
"format": "binary"
},
"request": {
"type": "string",
"description": "JSON string with import config",
"format": "json"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Import job created successfully",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/ImportJob"
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/table/{tableName}/sample": {
"get": {
"tags": [
"Data -- Internal Tables"
],
"summary": "Get Sample CSV",
"description": "Returns a downloadable sample CSV file for the specified internal table in a project.\n\nThis CSV sample contains a few rows of mock or representative data from the table's schema.\nIt helps users understand the structure of the table and prepare matching CSV files for import.\n\n#### Response\n- Content-Type: `text/csv`\n- Disposition: Attachment (`sample.csv`)\n- The first row contains column headers.\n- The following rows contain example values for each column.\n\n#### Example Output\n```\ntext,num19,numcol,decimalcol\n\"sample text\",1176,1044,77.3711303273\n\"sample text\",9354,7923,96.6658831270\n\"sample text\",7658,8750,30.3928941706\n```\n\nThis sample can be used as a template when preparing files to upload using the `/import` endpoint.\n",
"operationId": "csvSample",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "tableName",
"in": "path",
"description": "Name of the table",
"required": true,
"schema": {
"type": "string"
},
"example": "customers"
}
],
"responses": {
"200": {
"description": "Sample CSV returned successfully",
"content": {
"text/csv": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/queries": {
"get": {
"tags": [
"Data -- Queries"
],
"summary": "List Queries",
"description": "Returns all queries belonging to the given project. Each query includes its path and folderId if it is placed in a folder.",
"operationId": "listQueries",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
}
],
"responses": {
"200": {
"description": "List of queries",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Query"
}
},
"example": [
{
"id": "709891320440684892",
"displayName": "sample2",
"name": "sample2",
"inputQuery": "",
"path": "/reports/monthly",
"folderId": "f_3np1a"
},
{
"id": "702142445051183684",
"displayName": "deneme",
"name": "deneme",
"inputQuery": "SELECT count(*) from \"examplestripecatalogname\".\"payment\".\"customers\""
},
{
"id": "709891051854233848",
"displayName": "sample",
"name": "sample",
"inputQuery": "",
"path": "/reports/monthly",
"folderId": "f_3np1a"
},
{
"id": "709922802836177297",
"displayName": "sampleQuery",
"name": "samplequery",
"inputQuery": "SELECT * from \"mycatalog\".payment.charges"
},
{
"id": "709922802836177298",
"displayName": "dailyRevenue",
"name": "dailyrevenue",
"inputQuery": "SELECT * from \"mycatalog\".payment.charges",
"queryType": "MATERIALIZED",
"schedule": {
"type": "cron",
"cronExpression": "0 0 * * *",
"timezone": "UTC"
}
}
]
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"post": {
"tags": [
"Data -- Queries"
],
"summary": "Create Query",
"description": "Creates a new query under the given project. Supports plain and materialized query types. Optionally accepts a path to place the query in a folder hierarchy. A MATERIALIZED query is materialized immediately on create and its result is queryable as `\"peaka\".\"mtquery\".\"\n \n\n"
}
}
},
"/data/projects/{projectId}/queries/execute": {
"post": {
"tags": [
"Data -- Queries"
],
"summary": "Execute Query",
"description": "Executes a query and returns the result. Accepts a query builder object, a query ID, a query name, or a raw SQL statement.\n\nThe **`format`** query parameter controls the shape of the `data` array in the response:\n\n| Value | Description |\n|-------|-------------|\n| `CELL_TYPED` *(default)* | Each cell is an object with `name`, `displayName`, `dataType`, `order`, and `value`. |\n| `SIMPLE` | Each row is a flat JSON object whose keys are the column names. |\n| `COMPACT` | Each row is a plain array of values ordered by column position. |\n",
"operationId": "executeQuery",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "format",
"in": "query",
"description": "Response format: CELL_TYPED (default), SIMPLE, or COMPACT",
"required": false,
"schema": {
"type": "string",
"default": "CELL_TYPED",
"enum": [
"CELL_TYPED",
"SIMPLE",
"COMPACT"
]
},
"example": "SIMPLE"
}
],
"requestBody": {
"description": "Execute Query Request",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/QueryExecuteRequest"
},
{
"$ref": "#/components/schemas/QueryExecuteRequestId"
},
{
"$ref": "#/components/schemas/QueryExecuteRequestName"
},
{
"$ref": "#/components/schemas/QueryExecuteRequestStatement"
}
]
},
"examples": {
"Execute by Query Builder": {
"description": "Execute by Query Builder",
"value": {
"from": [
{
"catalogName": "peaka",
"schemaName": "query",
"tableName": "samplequery"
}
]
}
},
"Execute by Query Builder with Limit": {
"description": "Execute by Query Builder with Limit",
"value": {
"columns": [
"amount"
],
"from": [
{
"catalogName": "peaka",
"schemaName": "query",
"tableName": "samplequery"
}
],
"filters": null,
"limit": 3,
"offset": 0,
"orderBy": null
}
},
"Execute by Query Builder with Filter and Order By": {
"description": "Execute by Query Builder with Filter and Order By",
"value": {
"columns": [
"amount"
],
"from": [
{
"catalogName": "wilderman_green",
"schemaName": "payment",
"tableName": "charges"
}
],
"filters": {
"and": [
[
{
"column": {
"catalogName": "wilderman_green",
"schemaName": "payment",
"tableName": "charges",
"columnName": "amount"
}
},
">",
[
150
]
]
]
},
"limit": 50,
"offset": 0,
"orderBy": [
"amount DESC"
]
}
},
"Execute by Query ID": {
"description": "Execute by Query ID",
"value": {
"id": "709922802836177297"
}
},
"Execute by Query Name": {
"description": "Execute by Query Name",
"value": {
"qualifiedName": "peaka.query.samplequery"
}
},
"Execute by SQL Statement": {
"description": "Execute by SQL Statement",
"value": {
"statement": "SELECT * FROM \"peaka\".\"query\".\"samplequery\""
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Query Result",
"content": {
"application/json": {
"examples": {
"CELL_TYPED (default)": {
"description": "CELL_TYPED (default)",
"value": {
"columns": [
{
"catalogName": "peaka",
"schemaName": "query",
"tableName": "samplequery",
"columnName": "event"
},
{
"catalogName": "peaka",
"schemaName": "query",
"tableName": "samplequery",
"columnName": "distinct_id"
}
],
"data": [
[
{
"name": "event",
"displayName": "event",
"dataType": "varchar",
"order": 0,
"value": "$mp_web_page_view"
},
{
"name": "distinct_id",
"displayName": "distinct_id",
"dataType": "varchar",
"order": 1,
"value": "$device:916806fd-8a6c-425b-b5f9-b76b5d6f9d55"
}
]
]
}
},
"SIMPLE": {
"description": "SIMPLE",
"value": {
"columns": [
{
"catalogName": "peaka",
"schemaName": "query",
"tableName": "samplequery",
"columnName": "event"
},
{
"catalogName": "peaka",
"schemaName": "query",
"tableName": "samplequery",
"columnName": "distinct_id"
}
],
"data": [
{
"event": "$mp_web_page_view",
"distinct_id": "$device:916806fd-8a6c-425b-b5f9-b76b5d6f9d55"
}
]
}
},
"COMPACT": {
"description": "COMPACT",
"value": {
"columns": [
{
"catalogName": "peaka",
"schemaName": "query",
"tableName": "samplequery",
"columnName": "event"
},
{
"catalogName": "peaka",
"schemaName": "query",
"tableName": "samplequery",
"columnName": "distinct_id"
}
],
"data": [
[
"$mp_web_page_view",
"$device:916806fd-8a6c-425b-b5f9-b76b5d6f9d55"
]
]
}
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/queries/{queryId}": {
"get": {
"tags": [
"Data -- Queries"
],
"summary": "Read Query",
"description": "Returns a single query by its ID. Includes path and folderId if the query is placed in a folder.",
"operationId": "readQuery",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "queryId",
"in": "path",
"description": "ID of the Query",
"required": true,
"schema": {
"type": "string"
},
"example": 709922802836177300
}
],
"responses": {
"200": {
"description": "Read Query",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Query"
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"put": {
"tags": [
"Data -- Queries"
],
"summary": "Update Query",
"description": "Updates the display name, SQL, or schedule of an existing query. Fields omitted from the request keep their current values. Sending `queryType: MATERIALIZED` converts a plain query into a materialized one. Sending `inputQueryRefId` re-resolves the referenced query's SQL and stores the fresh snapshot as this query's `inputQuery` — use it to re-sync a materialized query with its source. To move a query to a different folder use the Update Query Path endpoint.",
"operationId": "updateQuery",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "queryId",
"in": "path",
"description": "ID of the Query",
"required": true,
"schema": {
"type": "string"
},
"example": 709922802836177300
},
{
"name": "checkSchemaExists",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"default": true
}
}
],
"requestBody": {
"description": "Query Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryRequest"
},
"examples": {
"Update Query": {
"description": "Update Query",
"value": {
"displayName": "sampleQuery",
"inputQuery": "SELECT * from \"mycatalog\".payment.charges"
}
},
"Update Materialized Query (Interval Schedule)": {
"description": "Update Materialized Query (Interval Schedule)",
"value": {
"displayName": "sampleQuery",
"inputQuery": "SELECT * from \"mycatalog\".payment.charges",
"queryType": "MATERIALIZED",
"schedule": {
"type": "interval",
"repeatDuration": "PT6H"
}
}
},
"Update Materialized Query (Cron Schedule)": {
"description": "Update Materialized Query (Cron Schedule)",
"value": {
"displayName": "sampleQuery",
"inputQuery": "SELECT * from \"mycatalog\".payment.charges",
"queryType": "MATERIALIZED",
"schedule": {
"type": "cron",
"cronExpression": "0 0 * * *",
"timezone": "UTC"
}
}
},
"Re-sync Materialized Query from Source Query": {
"description": "Re-resolves the referenced query's SQL and stores the fresh snapshot as this query's inputQuery.",
"value": {
"displayName": "sampleQuery",
"queryType": "MATERIALIZED",
"inputQueryRefId": "709922802836177297"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Query updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Query"
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"delete": {
"tags": [
"Data -- Queries"
],
"summary": "Delete Query",
"description": "Permanently deletes a query by its ID.",
"operationId": "deleteQuery",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "queryId",
"in": "path",
"description": "ID of the Query",
"required": true,
"schema": {
"type": "string"
},
"example": 709922802836177300
}
],
"responses": {
"200": {
"description": "Query deleted successfully"
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/queries/{queryId}/path": {
"patch": {
"tags": [
"Data -- Queries"
],
"summary": "Update Query Path",
"description": "Moves a query to the specified folder path. The path is resolved by the backend service.",
"operationId": "updateQueryPath",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "queryId",
"in": "path",
"description": "ID of the Query",
"required": true,
"schema": {
"type": "string"
},
"example": 709922802836177300
}
],
"requestBody": {
"description": "Path Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryPathUpdateRequest"
},
"example": {
"path": "/reports/monthly"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Path updated"
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/queries/folders": {
"get": {
"tags": [
"Data -- Query Folders"
],
"summary": "List Query Folders",
"description": "Returns all query folders belonging to the given project as a flat list.",
"operationId": "listQueryFolders",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
}
],
"responses": {
"200": {
"description": "Folders listed successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryFolderListResponse"
},
"example": {
"items": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Reports",
"path": "/Reports",
"parentId": null,
"createdAt": "2025-01-15T10:30:00Z"
},
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Monthly",
"path": "/Reports/Monthly",
"parentId": "550e8400-e29b-41d4-a716-446655440000",
"createdAt": "2025-01-15T10:31:00Z"
}
]
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"post": {
"tags": [
"Data -- Query Folders"
],
"summary": "Create Query Folder",
"description": "Creates a new query folder at the root level. The folder name is used to build the path (e.g. folderName \"Reports\" becomes path \"/Reports\"). Intermediate parent folders are created automatically if a nested path is provided.",
"operationId": "createQueryFolderAtRoot",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
}
],
"requestBody": {
"description": "Folder creation request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryFolderCreateRequest"
},
"example": {
"folderName": "Reports"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Folder created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryFolderItem"
},
"example": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Reports",
"path": "/Reports",
"parentId": null,
"createdAt": "2025-01-15T10:30:00Z"
}
}
}
},
"409": {
"description": "Folder already exists at this path",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/QueryFolderItem"
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/queries/folders/tree": {
"get": {
"tags": [
"Data -- Query Folders"
],
"summary": "Get Query Folder Tree",
"description": "Returns the folder hierarchy as a tree structure. Optionally includes queries within each folder node. Use rootFolderId to get a subtree starting from a specific folder.",
"operationId": "getQueryFolderTree",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "includeQueries",
"in": "query",
"description": "Whether to include queries within each folder node",
"required": false,
"schema": {
"type": "boolean",
"default": false
},
"example": true
},
{
"name": "rootFolderId",
"in": "query",
"description": "ID of the root folder to start the subtree from",
"required": false,
"schema": {
"type": "string"
},
"example": "550e8400-e29b-41d4-a716-446655440000"
}
],
"responses": {
"200": {
"description": "Folder tree retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryFolderTreeResponse"
},
"example": {
"tree": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Reports",
"path": "/Reports",
"children": [
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Monthly",
"path": "/Reports/Monthly",
"children": [],
"queries": []
}
],
"queries": [
{
"id": "709922802836177297",
"displayName": "Revenue Report",
"name": "revenuereport",
"inputQuery": "SELECT * FROM revenue"
}
]
}
]
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/queries/folders/{folderId}": {
"get": {
"tags": [
"Data -- Query Folders"
],
"summary": "Read Query Folder",
"description": "Returns a single folder by its ID, including its direct child folders and the queries it contains.",
"operationId": "readQueryFolder",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "folderId",
"in": "path",
"description": "ID of the Query Folder",
"required": true,
"schema": {
"type": "string"
},
"example": "550e8400-e29b-41d4-a716-446655440000"
}
],
"responses": {
"200": {
"description": "Folder read successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryFolderWithContentsResponse"
},
"example": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Reports",
"path": "/Reports",
"parentId": null,
"createdAt": "2025-01-15T10:30:00Z",
"folders": [
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Monthly",
"path": "/Reports/Monthly",
"parentId": "550e8400-e29b-41d4-a716-446655440000",
"createdAt": "2025-01-15T10:31:00Z"
}
],
"queries": [
{
"id": "709922802836177297",
"displayName": "Revenue Report",
"name": "revenuereport",
"inputQuery": "SELECT * FROM revenue",
"path": "/Reports",
"folderId": "550e8400-e29b-41d4-a716-446655440000"
}
]
}
}
}
},
"404": {
"description": "Folder not found",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/QueryFolderWithContentsResponse"
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"put": {
"tags": [
"Data -- Query Folders"
],
"summary": "Add/Remove Queries In/From Folder",
"description": "Moves queries into or out of a folder. Queries in queryIdsAdded are moved to the folder's path, queries in queryIdsRemoved are moved to root (\"/\").",
"operationId": "addOrRemoveQueryFromFolder",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "folderId",
"in": "path",
"description": "ID of the Query Folder",
"required": true,
"schema": {
"type": "string"
},
"example": "550e8400-e29b-41d4-a716-446655440000"
}
],
"requestBody": {
"description": "Query add/remove request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryFolderUpdateRequest"
},
"example": {
"queryIdsAdded": [
"709922802836177297"
],
"queryIdsRemoved": [
"709891320440684892"
]
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Queries moved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryFolderWithContentsResponse"
}
}
}
},
"404": {
"description": "Folder not found",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/QueryFolderWithContentsResponse"
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"delete": {
"tags": [
"Data -- Query Folders"
],
"summary": "Delete Query Folder",
"description": "Deletes a query folder by its ID. By default, only empty folders can be deleted. Set force=true to recursively delete the folder along with all its sub-folders and contained queries.",
"operationId": "deleteQueryFolder",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "folderId",
"in": "path",
"description": "ID of the Query Folder",
"required": true,
"schema": {
"type": "string"
},
"example": "550e8400-e29b-41d4-a716-446655440000"
},
{
"name": "force",
"in": "query",
"description": "If true, recursively deletes the folder along with all sub-folders and queries",
"required": false,
"schema": {
"type": "boolean",
"default": false
},
"example": false
}
],
"responses": {
"204": {
"description": "Folder deleted successfully"
},
"404": {
"description": "Folder not found"
},
"409": {
"description": "Folder is not empty (use force=true to delete)"
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/queries/folders/{folderId}/name": {
"patch": {
"tags": [
"Data -- Query Folders"
],
"summary": "Rename Query Folder",
"description": "Renames a query folder. The folder's path segments are updated to reflect the new name.",
"operationId": "renameQueryFolder",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "folderId",
"in": "path",
"description": "ID of the Query Folder",
"required": true,
"schema": {
"type": "string"
},
"example": "550e8400-e29b-41d4-a716-446655440000"
}
],
"requestBody": {
"description": "Rename request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryFolderRenameRequest"
},
"example": {
"name": "Archived Reports"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Folder renamed successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryFolderItem"
},
"example": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Archived Reports",
"path": "/Archived Reports",
"parentId": null,
"createdAt": "2025-01-15T10:30:00Z"
}
}
}
},
"404": {
"description": "Folder not found",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/QueryFolderItem"
}
}
}
},
"409": {
"description": "A folder with this name already exists at the same level",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/QueryFolderItem"
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/queries/folders/{folderId}/path": {
"patch": {
"tags": [
"Data -- Query Folders"
],
"summary": "Move Query Folder",
"description": "Moves a query folder to a new path in the hierarchy. All child folders and their paths are updated accordingly.",
"operationId": "moveQueryFolder",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "folderId",
"in": "path",
"description": "ID of the Query Folder to move",
"required": true,
"schema": {
"type": "string"
},
"example": "550e8400-e29b-41d4-a716-446655440000"
}
],
"requestBody": {
"description": "Move request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryPathUpdateRequest"
},
"example": {
"path": "/Archive/Reports"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Folder moved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryFolderItem"
},
"example": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Reports",
"path": "/Archive/Reports",
"parentId": "550e8400-e29b-41d4-a716-446655440002",
"createdAt": "2025-01-15T10:30:00Z"
}
}
}
},
"404": {
"description": "Folder not found",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/QueryFolderItem"
}
}
}
},
"409": {
"description": "A folder already exists at the target path or circular move detected",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/QueryFolderItem"
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/queries/folders/{parentFolderId}": {
"post": {
"tags": [
"Data -- Query Folders"
],
"summary": "Create Query Folder Under Parent",
"description": "Creates a new query folder as a child of the specified parent folder. The gateway resolves the parent folder's path and creates the new folder at \"{parentPath}/{folderName}\".",
"operationId": "createQueryFolderWithParentId",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "parentFolderId",
"in": "path",
"description": "ID of the parent Query Folder",
"required": true,
"schema": {
"type": "string"
},
"example": "550e8400-e29b-41d4-a716-446655440000"
}
],
"requestBody": {
"description": "Folder creation request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryFolderCreateRequest"
},
"example": {
"folderName": "Monthly"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Folder created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryFolderItem"
},
"example": {
"id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Monthly",
"path": "/Reports/Monthly",
"parentId": "550e8400-e29b-41d4-a716-446655440000",
"createdAt": "2025-01-15T10:31:00Z"
}
}
}
},
"404": {
"description": "Parent folder not found",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/QueryFolderItem"
}
}
}
},
"409": {
"description": "Folder already exists at this path",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/QueryFolderItem"
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/semantic-catalogs": {
"post": {
"tags": [
"Data -- Semantic Catalogs"
],
"summary": "Create a semantic catalog",
"description": "Creates a new Semantic Catalog in the specified Project. A Semantic Catalog is a virtual catalog that groups Semantic Tables, which are backed by saved queries.\n",
"operationId": "createSemanticCatalog",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
}
],
"requestBody": {
"description": "Semantic Catalog Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SemanticCatalogRequest"
},
"example": {
"name": "myCatalog"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Catalog created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Catalog"
},
"example": {
"id": "688890918747898103",
"name": "myCatalog",
"displayName": "myCatalog",
"type": "SEMANTIC"
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/semantic-catalogs/{catalogId}": {
"post": {
"tags": [
"Data -- Semantic Catalogs"
],
"summary": "Create a semantic table",
"description": "Creates a new Semantic Table within a Semantic Catalog. A Semantic Table maps a saved query to a table, making it queryable via SQL like any other table.\n",
"operationId": "createSemanticTable",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "catalogId",
"in": "path",
"description": "ID of the Semantic Catalog",
"required": true,
"schema": {
"type": "string"
},
"example": 688890918747898100
}
],
"requestBody": {
"description": "Semantic Table Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SemanticTableRequest"
},
"example": {
"schemaName": "mySchema",
"tableName": "myTableName",
"queryId": "788890918747898752"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Table created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SemanticTable"
},
"example": {
"tableId": "688890918747898103",
"catalogName": "myCatalog",
"schemaName": "mySchema",
"tableName": "myTableName"
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/semantic-catalogs/{catalogId}/share": {
"post": {
"tags": [
"Data -- Semantic Catalogs"
],
"summary": "Share Semantic Catalog",
"description": "Shares a Semantic Catalog with another Project. The target Project gains read access to the catalog's schemas and tables.\n",
"operationId": "shareSemanticTable",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "catalogId",
"in": "path",
"description": "ID of the Semantic Catalog to share",
"required": true,
"schema": {
"type": "string"
},
"example": 688890918747898100
}
],
"requestBody": {
"description": "Share Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CatalogShareRequest"
},
"example": {
"target": "MQtMNNBY"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Table shared"
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/semantic-catalogs/{catalogId}/table/{tableId}": {
"delete": {
"tags": [
"Data -- Semantic Catalogs"
],
"summary": "Delete a semantic table",
"description": "Deletes the specified Semantic Table from a Semantic Catalog.\n",
"operationId": "deleteSemanticTable",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "catalogId",
"in": "path",
"description": "ID of the Semantic Catalog",
"required": true,
"schema": {
"type": "string"
},
"example": 688890918747898100
},
{
"name": "tableId",
"in": "path",
"description": "ID of the Semantic Table",
"required": true,
"schema": {
"type": "string"
},
"example": 688890918747898100
}
],
"responses": {
"200": {
"description": "Table deleted"
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/cache": {
"post": {
"tags": [
"Data -- Cache"
],
"summary": "Create Cache",
"description": "Creates a new cache for a specific table in a catalog. Caching copies data from an external data source into the internal Peaka BigTable store for faster query performance.\n\nNot every table can be cached: check `isCacheable` and `supportedCacheTypes` in the List Tables response before creating a cache. `supportedCacheTypes` tells which of the modes below are available for the table (`FULL_REFRESH`, `INCREMENTAL`).\n\nThe cache can be configured in three modes:\n- **One-time cache**: No schedules provided. Data is cached once during creation and never automatically refreshed.\n- **Scheduled incremental updates**: Provide `incrementalCacheSchedule` to periodically sync only the changes (inserts, updates, deletes) since the last sync.\n- **Scheduled full refresh + incremental**: Provide both `fullRefreshCacheSchedule` and `incrementalCacheSchedule`. Full refresh drops and rebuilds the entire cached table periodically, while incremental updates run more frequently between full refreshes.\n\nAfter creation, the initial sync is triggered automatically based on the provided schedules. If only an incremental schedule is given, an incremental sync starts immediately. If a full refresh schedule is given, a full refresh starts immediately.\n\nThe schedule `expression` uses ISO-8601 duration format (e.g. `PT6H` = every 6 hours, `PT15M` = every 15 minutes, `P1D` = every day).",
"operationId": "createCache",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "The unique identifier of the project that owns the data source",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
}
],
"requestBody": {
"description": "Cache creation request specifying the target table and optional sync schedules",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CacheRequest"
},
"examples": {
"One-Time Cache": {
"description": "Creates a cache with no automatic refresh. Data is synced once at creation time.",
"value": {
"id": "960bd651-7b3c-4511-9a88-18e14ac7742a",
"catalogId": "627249916703408649",
"schemaName": "payment",
"tableName": "customers"
}
},
"Incremental Schedule Only": {
"description": "Creates a cache that incrementally syncs changes every 6 hours. Only new/updated/deleted rows since the last sync are processed.",
"value": {
"id": "960bd651-7b3c-4511-9a88-18e14ac7742a",
"catalogId": "627249916703408649",
"schemaName": "payment",
"tableName": "customers",
"incrementalCacheSchedule": {
"type": "BASIC",
"expression": "PT6H"
}
}
},
"Full Refresh + Incremental Schedule": {
"description": "Creates a cache with both schedules. Incremental sync runs every 6 hours for fast delta updates, and a full refresh rebuilds the entire cache every 24 hours to ensure consistency.",
"value": {
"id": "960bd651-7b3c-4511-9a88-18e14ac7742a",
"catalogId": "627249916703408649",
"schemaName": "payment",
"tableName": "customers",
"fullRefreshCacheSchedule": {
"type": "BASIC",
"expression": "PT24H"
},
"incrementalCacheSchedule": {
"type": "BASIC",
"expression": "PT6H"
}
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Cache created successfully. Returns the created cache configuration including its generated ID and schedules.",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/Cache"
}
}
}
},
"400": {
"description": "Invalid request. The catalog, schema, or table may not exist, or the schedule expression is invalid. When the table is not cacheable (`isCacheable: false` in the table metadata), the error body carries `errorCode: TABLE_NOT_CACHEABLE`.",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/Cache"
}
}
}
},
"409": {
"description": "A cache already exists for this table.",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/Cache"
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/cache/batch": {
"post": {
"tags": [
"Data -- Cache"
],
"summary": "Create Batch Cache",
"description": "Creates multiple caches in a single request. Each item in the array follows the same schema as the single create cache endpoint. Caches are created independently; if one fails, the others may still succeed.\n\nThe response contains a list of results, one per requested cache, each indicating success or failure. On success, the created cache object is included. On failure, the error message is provided.\n\nThis is useful when enabling caching for multiple tables at once (e.g. during initial project setup).",
"operationId": "createBatchCache",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "The unique identifier of the project that owns the data sources",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
}
],
"requestBody": {
"description": "Array of cache creation requests. Each element specifies a table to cache with optional sync schedules.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CacheRequest"
}
},
"examples": {
"Create Multiple Caches": {
"description": "Creates three caches: one without schedules, one with incremental only, and one with both full refresh and incremental schedules.",
"value": [
{
"catalogId": "627249916703408649",
"schemaName": "payment",
"tableName": "customers"
},
{
"catalogId": "627249916703408649",
"schemaName": "payment",
"tableName": "charges",
"incrementalCacheSchedule": {
"type": "BASIC",
"expression": "PT6H"
}
},
{
"catalogId": "627249916703408649",
"schemaName": "payment",
"tableName": "invoices",
"fullRefreshCacheSchedule": {
"type": "BASIC",
"expression": "PT24H"
},
"incrementalCacheSchedule": {
"type": "BASIC",
"expression": "PT6H"
}
}
]
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Batch processing completed. Each entry in the response array indicates whether that specific cache was created successfully or failed.",
"content": {
"*/*": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CacheCreateStatus"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/cache/status": {
"get": {
"tags": [
"Data -- Cache"
],
"summary": "Get All Cache Statuses of a Project",
"description": "Returns the status of all caches within a project. Each entry in the response array contains the same status information as the single cache status endpoint, including execution details for both sync types.\n\nThis is useful for building a dashboard view that shows the health and progress of all cached tables in a project.",
"operationId": "getCacheStatusByProject",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "The unique identifier of the project to list cache statuses for",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
}
],
"responses": {
"200": {
"description": "List of cache statuses for all caches in the project. Returns an empty array if no caches exist.",
"content": {
"*/*": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CacheStatus"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/cache/{cacheId}": {
"get": {
"tags": [
"Data -- Cache"
],
"summary": "Get Cache Settings",
"description": "Retrieves the configuration of a specific cache, including the target catalog, schema, table, and the configured incremental and full refresh schedules.\n\nUse this endpoint to inspect a cache's current settings before updating them, or to confirm the schedule configuration of a cache after creation. To check the runtime status (last execution, progress, errors) of the cache, use the Get Cache Status endpoint instead.",
"operationId": "getCacheSettings",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "The unique identifier of the project that owns the cache",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "cacheId",
"in": "path",
"description": "The unique identifier of the cache to retrieve (UUID format)",
"required": true,
"schema": {
"type": "string"
},
"example": "960bd651-7b3c-4511-9a88-18e14ac7742a"
}
],
"responses": {
"200": {
"description": "Cache settings retrieved successfully.",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/Cache"
}
}
}
},
"404": {
"description": "Cache not found for the given cacheId.",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/Cache"
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"put": {
"tags": [
"Data -- Cache"
],
"summary": "Update Cache Settings",
"description": "Updates the sync schedules of an existing cache. Use this to change how frequently the cache is refreshed.\n\nOnly schedule fields are updated; the target table, catalog, and schema cannot be changed after creation. When a schedule is changed, any previously running scheduled workflow for that mode is replaced with the new schedule. Set a schedule's `type` to `NONE` to disable that particular sync mode.\n\nThe schedule `expression` uses ISO-8601 duration format (e.g. `PT6H` = every 6 hours, `PT15M` = every 15 minutes, `P1D` = every day).",
"operationId": "updateCacheSettings",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "The unique identifier of the project that owns the cache",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "cacheId",
"in": "path",
"description": "The unique identifier of the cache to update (UUID format)",
"required": true,
"schema": {
"type": "string"
},
"example": "960bd651-7b3c-4511-9a88-18e14ac7742a"
}
],
"requestBody": {
"description": "Updated schedule configuration. Only the provided schedule fields are updated.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CacheSettingsUpdateRequest"
},
"examples": {
"Update Both Schedules": {
"description": "Sets full refresh to every 24 hours and incremental sync to every 6 hours.",
"value": {
"fullRefreshCacheSchedule": {
"type": "BASIC",
"expression": "PT24H"
},
"incrementalCacheSchedule": {
"type": "BASIC",
"expression": "PT6H"
}
}
},
"Disable Full Refresh": {
"description": "Disables the full refresh schedule while keeping incremental sync active.",
"value": {
"fullRefreshCacheSchedule": {
"type": "NONE"
},
"incrementalCacheSchedule": {
"type": "BASIC",
"expression": "PT1H"
}
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Cache settings updated successfully. Returns the updated cache configuration.",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/Cache"
}
}
}
},
"400": {
"description": "Invalid request, e.g. the schedule expression is invalid.",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/Cache"
}
}
}
},
"404": {
"description": "Cache not found for the given cacheId.",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/Cache"
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"delete": {
"tags": [
"Data -- Cache"
],
"summary": "Delete Cache",
"description": "Permanently deletes a cache and all its associated data. This operation:\n- Cancels any running or scheduled sync workflows (both incremental and full refresh).\n- Drops the cached table from the internal BigTable store.\n- Removes all cache settings, execution history, and status records.\n\nThis action is irreversible. To re-cache the table, a new cache must be created from scratch.",
"operationId": "deleteCache",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "The unique identifier of the project that owns the cache",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "cacheId",
"in": "path",
"description": "The unique identifier of the cache to delete (UUID format)",
"required": true,
"schema": {
"type": "string"
},
"example": "960bd651-7b3c-4511-9a88-18e14ac7742a"
}
],
"responses": {
"200": {
"description": "Cache deleted successfully."
},
"404": {
"description": "Cache not found for the given cacheId."
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/cache/{cacheId}/cancelFullRefreshUpdate": {
"post": {
"tags": [
"Data -- Cache"
],
"summary": "Cancel Running Full Refresh",
"description": "Cancels a currently running full refresh (resync) workflow for the specified cache. This sends a cancellation signal to the underlying Temporal workflow.\n\nThe cancellation is best-effort: if the workflow has already completed or is in its final stages, the cancel request may have no effect. Only workflows with a RUNNING status can be cancelled.\n\nAfter successful cancellation, the cache status transitions to CANCELLED. The previously cached data remains intact (the partial refresh data is discarded). A new full refresh or incremental sync can be triggered after cancellation.\n\nThis endpoint only affects the full refresh workflow. To cancel an incremental sync, use the Cancel Incremental Update endpoint instead.",
"operationId": "cancelFullRefreshCache",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "The unique identifier of the project that owns the cache",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "cacheId",
"in": "path",
"description": "The unique identifier of the cache whose full refresh should be cancelled (UUID format)",
"required": true,
"schema": {
"type": "string"
},
"example": "960bd651-7b3c-4511-9a88-18e14ac7742a"
}
],
"responses": {
"200": {
"description": "Cancellation signal sent successfully. Check cache status to confirm the workflow was cancelled."
},
"404": {
"description": "Cache not found or no running full refresh workflow exists for this cache."
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/cache/{cacheId}/cancelIncrementalUpdate": {
"post": {
"tags": [
"Data -- Cache"
],
"summary": "Cancel Running Incremental Update",
"description": "Cancels a currently running incremental sync workflow for the specified cache. This sends a cancellation signal to the underlying Temporal workflow.\n\nThe cancellation is best-effort: if the workflow has already completed or is in its final stages, the cancel request may have no effect. Only workflows with a RUNNING status can be cancelled.\n\nAfter successful cancellation, the cache status transitions to CANCELLED. Data that was already synced before the cancellation remains in the cache. A new incremental sync or full refresh can be triggered after cancellation.\n\nThis endpoint only affects the incremental sync workflow. To cancel a full refresh, use the Cancel Full Refresh Update endpoint instead.",
"operationId": "cancelIncrementalCache",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "The unique identifier of the project that owns the cache",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "cacheId",
"in": "path",
"description": "The unique identifier of the cache whose incremental sync should be cancelled (UUID format)",
"required": true,
"schema": {
"type": "string"
},
"example": "960bd651-7b3c-4511-9a88-18e14ac7742a"
}
],
"responses": {
"200": {
"description": "Cancellation signal sent successfully. Check cache status to confirm the workflow was cancelled."
},
"404": {
"description": "Cache not found or no running incremental sync workflow exists for this cache."
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/cache/{cacheId}/executionHistory": {
"get": {
"tags": [
"Data -- Cache"
],
"summary": "Get Cache Execution History",
"description": "Returns a paginated list of past sync executions for the specified cache, ordered from most recent to oldest. Each entry corresponds to one sync run (either incremental or full refresh) and includes its status, progress counters, error details (if failed), and lifecycle timestamps.\n\nThe `executionMode` field on each entry indicates whether that run was an incremental sync or a full refresh. Use the `limit` and `offset` query parameters to page through history; defaults are `limit=10` and `offset=0`.\n\nExecution records have a retention window of 14 days after the cache or run is finalised, after which they are automatically removed.",
"operationId": "getCacheExecutionHistory",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "The unique identifier of the project that owns the cache",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "cacheId",
"in": "path",
"description": "The unique identifier of the cache whose history is requested (UUID format)",
"required": true,
"schema": {
"type": "string"
},
"example": "960bd651-7b3c-4511-9a88-18e14ac7742a"
},
{
"name": "limit",
"in": "query",
"description": "Maximum number of execution records to return. Defaults to 10.",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"default": 10
},
"example": 10
},
{
"name": "offset",
"in": "query",
"description": "Number of records to skip from the start of the result set, used for pagination. Defaults to 0.",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"default": 0
},
"example": 0
}
],
"responses": {
"200": {
"description": "Execution history retrieved successfully. Returns an empty array if no executions exist for this cache.",
"content": {
"*/*": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CacheExecutionInfo"
}
}
}
}
},
"404": {
"description": "Cache not found for the given cacheId.",
"content": {
"*/*": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CacheExecutionInfo"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/cache/{cacheId}/fullRefreshUpdate": {
"post": {
"tags": [
"Data -- Cache"
],
"summary": "Trigger Full Refresh Cache Update",
"description": "Manually triggers a full refresh (resync) for the specified cache. This drops all existing cached data and rebuilds the cache from scratch by re-reading the entire source table.\n\nFull refresh is more expensive than incremental sync but ensures complete data consistency. It is useful when the source data has drifted or when schema changes have occurred. This is a one-time manual trigger that runs independently of any configured schedule.\n\nUse the Get Cache Status endpoint to monitor the progress of the triggered refresh. The `lastFullRefreshCacheExecution` field in the status response will reflect the new execution.",
"operationId": "fullRefreshCache",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "The unique identifier of the project that owns the cache",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "cacheId",
"in": "path",
"description": "The unique identifier of the cache to fully refresh (UUID format)",
"required": true,
"schema": {
"type": "string"
},
"example": "960bd651-7b3c-4511-9a88-18e14ac7742a"
}
],
"responses": {
"200": {
"description": "Full refresh triggered successfully.",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
},
"404": {
"description": "Cache not found for the given cacheId.",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/cache/{cacheId}/incrementalUpdate": {
"post": {
"tags": [
"Data -- Cache"
],
"summary": "Trigger Incremental Cache Update",
"description": "Manually triggers an incremental (delta) sync for the specified cache. This syncs only the rows that have changed (inserted, updated, or deleted) since the last successful sync.\n\nIncremental sync is faster than a full refresh because it processes only the delta. This is a one-time manual trigger that runs independently of any configured schedule. If an incremental sync is already running, this call may start a new workflow that will be queued.\n\nUse the Get Cache Status endpoint to monitor the progress of the triggered sync. The `lastIncrementalCacheExecution` field in the status response will reflect the new execution.",
"operationId": "incrementalUpdateCache",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "The unique identifier of the project that owns the cache",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "cacheId",
"in": "path",
"description": "The unique identifier of the cache to sync (UUID format)",
"required": true,
"schema": {
"type": "string"
},
"example": "960bd651-7b3c-4511-9a88-18e14ac7742a"
}
],
"responses": {
"200": {
"description": "Incremental sync triggered successfully.",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
},
"404": {
"description": "Cache not found for the given cacheId.",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/cache/{cacheId}/status": {
"get": {
"tags": [
"Data -- Cache"
],
"summary": "Get Cache Status",
"description": "Returns the current status of a specific cache, including execution details for both the last incremental sync and the last full refresh.\n\nThe top-level `status` field is computed from the most recent execution across both sync types:\n- `NOT_INITIALIZED`: No sync has ever been executed for this cache.\n- `RUNNING`: At least one sync (incremental or full refresh) is currently in progress.\n- `COMPLETED`: The most recent sync completed successfully.\n- `FAILED`: The most recent sync failed. Check the `error` field in the relevant execution info for details.\n- `CANCELLED`: The most recent sync was cancelled via a cancel endpoint.\n\nEach execution info object (`lastIncrementalCacheExecution`, `lastFullRefreshCacheExecution`) contains:\n- `id`: Unique execution identifier.\n- `status`: Execution-specific status (RUNNING, COMPLETED, FAILED, CANCELLED).\n- `progress`: Real-time progress with record counts (cached, inserted, updated, deleted).\n- `error`: Error details if the execution failed.\n- `createdAt`, `updatedAt`, `finishedAt`: Timestamps tracking execution lifecycle.\n\nUse `excludeLogs=true` to omit the `cacheActionLogs` array for a lighter response, especially when polling for status during an active sync.",
"operationId": "getCacheStatus",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "The unique identifier of the project that owns the cache",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "cacheId",
"in": "path",
"description": "The unique identifier of the cache to check (UUID format)",
"required": true,
"schema": {
"type": "string"
},
"example": "960bd651-7b3c-4511-9a88-18e14ac7742a"
},
{
"name": "excludeLogs",
"in": "query",
"description": "When true, omits the cacheActionLogs array from the response for a lighter payload. Defaults to false.",
"required": false,
"schema": {
"type": "boolean"
},
"example": true
}
],
"responses": {
"200": {
"description": "Cache status retrieved successfully.",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/CacheStatus"
}
}
}
},
"404": {
"description": "Cache not found for the given cacheId.",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/CacheStatus"
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/catalog/{catalogId}/cache/status": {
"get": {
"tags": [
"Data -- Cache"
],
"summary": "Get All Cache Statuses of a Catalog",
"description": "Returns the status of all caches within a specific catalog of a project. This filters the cache list to only those belonging to the given catalog, which is useful when managing caches per data source connection.\n\nEach entry in the response array contains the same status information as the single cache status endpoint.",
"operationId": "getCacheStatusByCatalog",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "The unique identifier of the project that owns the catalog",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "catalogId",
"in": "path",
"description": "The unique identifier of the catalog (data source connection) to filter caches by",
"required": true,
"schema": {
"type": "string"
},
"example": 627249916703408600
}
],
"responses": {
"200": {
"description": "List of cache statuses for all caches in the catalog. Returns an empty array if no caches exist for this catalog.",
"content": {
"*/*": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CacheStatus"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/catalog/{catalogId}/schema/{schemaName}/cache/status": {
"get": {
"tags": [
"Data -- Cache"
],
"summary": "Get All Cache Statuses of a Schema",
"description": "Returns the status of all caches within a specific schema of a catalog. This is a narrower filter than the catalog-level status endpoint, useful when a single catalog contains many schemas and only a subset is of interest.\n\nEach entry in the response array contains the same status information as the single cache status endpoint.",
"operationId": "getCacheStatusBySchema",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "The unique identifier of the project that owns the catalog",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "catalogId",
"in": "path",
"description": "The unique identifier of the catalog (data source connection) that owns the schema",
"required": true,
"schema": {
"type": "string"
},
"example": 627249916703408600
},
{
"name": "schemaName",
"in": "path",
"description": "The name of the schema to filter caches by",
"required": true,
"schema": {
"type": "string"
},
"example": "payment"
}
],
"responses": {
"200": {
"description": "List of cache statuses for all caches in the schema. Returns an empty array if no caches exist for this schema.",
"content": {
"*/*": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CacheStatus"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/queries/{queryId}/exports": {
"post": {
"tags": [
"Data -- Exports"
],
"summary": "Export Query (async)",
"description": "Submits an async export of a saved query as CSV or JSONL. Returns immediately with a job id; poll the status endpoint for the download URLs.",
"operationId": "exportQuery",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "queryId",
"in": "path",
"description": "ID of the Query",
"required": true,
"schema": {
"type": "string"
},
"example": 709922802836177300
}
],
"requestBody": {
"description": "Export options",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExportRequest"
},
"examples": {
"CSV": {
"description": "CSV",
"value": {
"format": "CSV",
"columns": [
"id",
"created",
"amount"
]
}
},
"JSONL": {
"description": "JSONL",
"value": {
"format": "JSONL"
}
},
"CSV + GZIP": {
"description": "CSV + GZIP",
"value": {
"format": "CSV",
"compression": "GZIP"
}
}
}
}
},
"required": true
},
"responses": {
"202": {
"description": "Export job accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExportJobCreated"
},
"example": {
"id": "4c9fcb44-126a-45f8-99a0-f1d245083d78",
"status": "PENDING"
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
},
"x-api-order": 1
}
},
"/data/projects/{projectId}/catalogs/{catalogId}/schemas/{schemaName}/tables/{tableName}/exports": {
"post": {
"tags": [
"Data -- Exports"
],
"summary": "Export Table (async)",
"description": "Submits an async export of a table as CSV or JSONL. Returns immediately with a job id; poll the status endpoint for the download URLs.",
"operationId": "exportTable",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "catalogId",
"in": "path",
"description": "ID of the Catalog",
"required": true,
"schema": {
"type": "string"
},
"example": 367189801096446900
},
{
"name": "schemaName",
"in": "path",
"description": "Schema name",
"required": true,
"schema": {
"type": "string"
},
"example": "payment"
},
{
"name": "tableName",
"in": "path",
"description": "Table name",
"required": true,
"schema": {
"type": "string"
},
"example": "charges"
}
],
"requestBody": {
"description": "Export options",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExportRequest"
},
"examples": {
"CSV": {
"description": "CSV",
"value": {
"format": "CSV",
"columns": [
"id",
"created",
"amount"
]
}
},
"JSONL": {
"description": "JSONL",
"value": {
"format": "JSONL"
}
},
"CSV + GZIP": {
"description": "CSV + GZIP",
"value": {
"format": "CSV",
"compression": "GZIP"
}
}
}
}
},
"required": true
},
"responses": {
"202": {
"description": "Export job accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExportJobCreated"
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
},
"x-api-order": 2
}
},
"/data/projects/{projectId}/exports": {
"get": {
"tags": [
"Data -- Exports"
],
"summary": "List Exports",
"description": "Returns the project's export jobs, newest first. Files are omitted from the list (call the single-export endpoint for download URLs); each item still carries `downloadable`.",
"operationId": "listExports",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "status",
"in": "query",
"description": "Comma-separated status filter: PENDING,RUNNING,SUCCEEDED,FAILED,CANCELLED. Examples: `SUCCEEDED,RUNNING` (active or done), `FAILED,CANCELLED` (unsuccessful), `SUCCEEDED` (single status). Omit to return every status.",
"required": false,
"schema": {
"type": "string"
},
"example": "SUCCEEDED,RUNNING"
},
{
"name": "limit",
"in": "query",
"description": "Page size, clamped to [1, 200]",
"required": false,
"schema": {
"type": "integer",
"format": "int32"
},
"example": 50
},
{
"name": "createdBefore",
"in": "query",
"description": "Keyset cursor (ISO-8601): the previous page's last createdAt. Example: `2026-06-10T15:23:26.893985Z`. Omit for the first page.",
"required": false,
"schema": {
"type": "string"
},
"example": "2026-06-10T15:23:26.893985Z"
}
],
"responses": {
"200": {
"description": "List of export jobs",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ExportJobResponse"
}
},
"examples": {
"Mixed statuses": {
"description": "Mixed statuses",
"value": [
{
"id": "4c9fcb44-126a-45f8-99a0-f1d245083d78",
"status": "SUCCEEDED",
"format": "JSONL",
"compression": "NONE",
"rowCount": 993,
"bytes": 3706920,
"durationMs": 1055,
"downloadable": true,
"queryId": "709922802836177297",
"source": "peaka.query.\"charges_view\"",
"userName": "user@example.com",
"apiKeyPrefix": "hBWIQxjc",
"clientSource": "peaka-studio",
"createdAt": "2026-06-10T12:24:08Z"
},
{
"id": "2f1a9c77-8b3e-4d21-9a5c-1e7f0b2d4a90",
"status": "RUNNING",
"format": "CSV",
"compression": "GZIP",
"downloadable": false,
"catalogId": "367189801096446904",
"schemaName": "payment",
"tableName": "charges",
"source": "peaka.payment.\"charges\"",
"userName": "user@example.com",
"apiKeyPrefix": "hBWIQxjc",
"clientSource": "peaka-api",
"createdAt": "2026-06-10T12:20:31Z"
},
{
"id": "9d8c7b6a-5e4f-3210-bca9-87654321fedc",
"status": "FAILED",
"format": "CSV",
"downloadable": false,
"error": "Query exceeded the 1,000,000 row export limit",
"queryId": "709922802836177297",
"source": "peaka.query.\"charges_view\"",
"userName": "user@example.com",
"apiKeyPrefix": "hBWIQxjc",
"clientSource": "peaka-studio",
"createdAt": "2026-06-10T12:11:02Z"
}
]
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
},
"x-api-order": 3
}
},
"/data/projects/{projectId}/exports/{exportId}": {
"get": {
"tags": [
"Data -- Exports"
],
"summary": "Read Export",
"description": "Returns the status of a single export job. For a SUCCEEDED job owned by the caller, `files` carries freshly-presigned download URLs; non-owners get the row with `downloadable=false`.",
"operationId": "readExport",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "exportId",
"in": "path",
"description": "Export job id (UUID)",
"required": true,
"schema": {
"type": "string"
},
"example": "4c9fcb44-126a-45f8-99a0-f1d245083d78"
}
],
"responses": {
"200": {
"description": "Export job status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExportJobResponse"
}
}
}
},
"404": {
"description": "Export job not found",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
},
"x-api-order": 4
},
"delete": {
"tags": [
"Data -- Exports"
],
"summary": "Cancel Export",
"description": "Cancels a PENDING/RUNNING export (kills the running query and cleans up partial artifacts). A no-op on an already-finished job. Idempotent.",
"operationId": "cancelExport",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "exportId",
"in": "path",
"description": "Export job id (UUID)",
"required": true,
"schema": {
"type": "string"
},
"example": "4c9fcb44-126a-45f8-99a0-f1d245083d78"
}
],
"responses": {
"204": {
"description": "Cancellation accepted"
}
},
"x-mint": {
"content": "\n \n \n\n"
},
"x-api-order": 5
}
},
"/data/projects/{projectId}/catalogs/{catalogId}/parametricTables": {
"get": {
"tags": [
"Data -- Parametric Tables"
],
"summary": "List Parametric Tables",
"description": "Lists all Parametric Tables defined under the specified catalog. A Parametric Table is a pre-configured view of a REST-based table with fixed query parameter values (e.g., `_q_account`), allowing it to be queried like a regular table without passing those parameters each time.",
"operationId": "listParametricTables",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "catalogId",
"in": "path",
"description": "ID of the catalog",
"required": true,
"schema": {
"type": "string"
},
"example": 846085284821991600
}
],
"responses": {
"200": {
"description": "List of parametric tables",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ParametricTable"
}
},
"examples": {
"Example List": {
"description": "Example List",
"value": [
{
"fromSchema": "public",
"fromTable": "products",
"toSchema": "analytics",
"toTable": "param_products",
"paramValues": [
{
"key": "country",
"value": "US"
},
{
"key": "year",
"value": 2024
}
]
}
]
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"post": {
"tags": [
"Data -- Parametric Tables"
],
"summary": "Create Parametric Table",
"description": "Creates a new Parametric Table under the specified catalog. A Parametric Table binds specific query parameter values to a source table from a REST catalog, producing a new named table (e.g., `xyz_customers`) that can be queried directly without supplying those parameters at query time. For example, if the source table `customers` requires a `_q_account` parameter, you can create a Parametric Table that fixes this value and exposes the result as a standalone table.\n\nDate and timestamp parameters also accept **relative-date macros**, re-evaluated on every query, so a table saved as \"this week's sales\" always returns the current week. Grammar: `@\n \n\n"
}
},
"delete": {
"tags": [
"Data -- Parametric Tables"
],
"summary": "Delete Parametric Table",
"description": "Deletes a Parametric Table identified by its target schema and table name. The original source table is not affected.",
"operationId": "deleteParametricTable",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "catalogId",
"in": "path",
"description": "ID of the catalog",
"required": true,
"schema": {
"type": "string"
},
"example": 846085284821991600
},
{
"name": "toSchema",
"in": "query",
"description": "Target schema of the parametric table",
"required": true,
"schema": {
"type": "string"
},
"example": "analytics"
},
{
"name": "toTable",
"in": "query",
"description": "Target table name of the parametric table",
"required": true,
"schema": {
"type": "string"
},
"example": "param_products"
}
],
"responses": {
"204": {
"description": "Parametric table deleted successfully"
},
"404": {
"description": "Parametric table not found"
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/ui/initSession": {
"get": {
"tags": [
"Embedded Peaka Api"
],
"summary": "Init Session (Deprecated)",
"description": "Deprecated. Use POST /ui/initSession instead, which supports feature flags, session modes, and additional configuration options.\n\nInitializes an Embedded Peaka session and returns a session URL. The returned URL can be used to embed the Peaka UI in an iframe.\n",
"operationId": "initSession_1",
"parameters": [
{
"name": "projectId",
"in": "query",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "timeoutInSeconds",
"in": "query",
"description": "Session timeout in seconds",
"required": false,
"schema": {
"type": "integer",
"format": "int32"
},
"example": 300
},
{
"name": "theme",
"in": "query",
"description": "Theme for the embedded UI (e.g., dark, light)",
"required": false,
"schema": {
"type": "string"
},
"example": "dark"
},
{
"name": "themeOverride",
"in": "query",
"description": "Whether to override the default theme",
"required": false,
"schema": {
"type": "boolean"
},
"example": true
}
],
"responses": {
"200": {
"description": "Session created successfully",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/EmbeddedSession"
},
"examples": {
"Session created successfully": {
"description": "Session created successfully",
"value": {
"sessionUrl": "https://partner.peaka.studio/api/v1/ui/session?code=2eccdbf31efa110943b470b9023e9a52587c166e4d1c21f23fabbcd7de5b74ab"
}
}
}
}
}
}
},
"deprecated": true,
"x-mint": {
"content": "\n \n \n\n"
}
},
"post": {
"tags": [
"Embedded Peaka Api"
],
"summary": "Init Session",
"description": "Initializes an Embedded Peaka session and returns a session URL that can be used to embed the Peaka UI in an iframe.\n\n[Embedded Peaka](https://docs.peaka.com/embedded-peaka/introduction) allows you to integrate Peaka's data management capabilities — including connections, catalogs, caching, queries, and a full UI — directly into your application.\n\nThe returned sessionUrl should be loaded inside an iframe. For security, direct iframe embedding requires enabling \"Embedded UI\" in Developer Settings and registering your domain over HTTPS.\n\n#### Configuration options\n- theme / themeOverride: Customize the look and feel of the embedded UI, including custom CSS theming.\n- featureFlags: Control visibility of UI sections (e.g., enable/disable queries, connectors).\n- sessionMode: Choose between FULL_STUDIO (complete Peaka experience) or CONNECTOR_MODAL_ONLY (streamlined connector setup).\n- connectorType: Pre-select a specific connector type when using connector-only mode.\n- autoCreateCatalog: Automatically create a catalog after a connection is established.\n\nSee also: [Data Management Tool with UI](https://docs.peaka.com/embedded-peaka/data-management-tool-with-ui)\n",
"operationId": "initSession",
"requestBody": {
"description": "Session Initialization Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InitSessionRequest"
},
"examples": {
"Session Initialization Request": {
"description": "Session Initialization Request",
"value": {
"timeoutInSeconds": 300,
"projectId": "projectId",
"theme": "dark",
"themeOverride": true,
"featureFlags": {
"feature1": true,
"feature2": false
}
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Session created successfully",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/EmbeddedSession"
},
"examples": {
"Session created successfully": {
"description": "Session created successfully",
"value": {
"sessionUrl": "https://partner.peaka.studio/api/v1/ui/session?code=2eccdbf31efa110943b470b9023e9a52587c166e4d1c21f23fabbcd7de5b74ab"
}
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/supportedDrivers": {
"get": {
"tags": [
"Supported Drivers"
],
"summary": "List Supported Drivers",
"description": "Returns connection strings for all supported drivers (JDBC, SQL Alchemy). These can be used to connect to Peaka's query engine from external tools.\n",
"operationId": "getSupportedDrivers",
"parameters": [
{
"name": "catalogName",
"in": "query",
"description": "Catalog name. \n\nDrivers such as sql_alchemy supports only one catalog at a time. So specific catalog name must be provided in order to use.",
"required": false,
"schema": {
"type": "string"
},
"example": "sampleHubSpotCatalog"
}
],
"responses": {
"200": {
"description": "List of supported drivers",
"content": {
"*/*": {
"schema": {
"type": "string"
},
"examples": {
"List of all drivers.": {
"description": "List of all drivers.",
"value": {
"JDBC": "jdbc:peaka://dbc.peaka.studio:4567/?extraCredentials=peakaKey:gk4aUnCO.IYxkP1NxP67YkVViqYGZd4INpUAr04TE",
"SQL_ALCHEMY": "peaka://dbc.peaka.studio:4567/{catalogName}?http_scheme=https&extra_credential=[[\"peakaKey\",\"gk4aUnCO.IYxkP1NxP67YkVViqYGZd4INpUAr04TE\"]]&access_token=true"
}
},
"List of all drivers with CatalogName": {
"description": "Drivers such as sql_alchemy supports only one catalog at a time. So specific catalog name must be provided in order to use.",
"value": {
"JDBC": "jdbc:peaka://dbc.peaka.studio:4567/?extraCredentials=peakaKey:gk4aUnCO.IYxkP1NxP67YkVViqYGZe3INpUAr04TE",
"SQL_ALCHEMY": "peaka://dbc.peaka.studio:4567/sampleCatalog?http_scheme=https&extra_credential=[[\"peakaKey\",\"gk4aUnCO.IYxkP1NxP67YkVViqYGZe3INpUAr04TE\"]]&access_token=true"
}
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/supportedDrivers/jdbc": {
"get": {
"tags": [
"Supported Drivers"
],
"summary": "Get JDBC Driver",
"description": "Returns the JDBC connection string for connecting to Peaka's query engine from JDBC-compatible tools.\n",
"operationId": "getJdbcDriver",
"responses": {
"200": {
"description": "Url for given driver",
"content": {
"*/*": {
"schema": {
"type": "string"
},
"examples": {
"JDBC driver": {
"description": "JDBC driver",
"value": "{\n \"JDBC\": \"jdbc:peaka://dbc.peaka.studio:4567/?extraCredentials=peakaKey:gk4aUnCO.IYxkP1NxP67YkVViqYGZe3INpUAr04TE\",\n}\n"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/supportedDrivers/sql_alchemy": {
"get": {
"tags": [
"Supported Drivers"
],
"summary": "Get SQL Alchemy Driver",
"description": "Returns the SQL Alchemy connection string for connecting to Peaka's query engine. SQL Alchemy supports only one catalog at a time, so a catalogName must be provided.\n",
"operationId": "getSqlAlchemyDriver",
"parameters": [
{
"name": "catalogName",
"in": "query",
"description": "Catalog name. \n\nDrivers such as sql_alchemy supports only one catalog at a time. So specific catalog name must be provided in order to use. ",
"required": true,
"schema": {
"type": "string"
},
"example": "sampleHubSpotCatalog"
}
],
"responses": {
"200": {
"description": "Url for given driver",
"content": {
"*/*": {
"schema": {
"type": "string"
},
"examples": {
"SQL_ALCHEMY driver with Catalog provided": {
"description": "Drivers such as sql_alchemy supports only one catalog at a time. So specific catalog name must be provided in order to use.",
"value": {
"SQL_ALCHEMY": "peaka://dbc.peaka.studio:4567/sampleCatalog?http_scheme=https&extra_credential=[[\"peakaKey\",\"gk4aUnCO.IYxkP1NxP67YkVViqYGZe3INpUAr04TE\"]]&access_token=true"
}
},
"SQL_ALCHEMY driver without Catalog not provided": {
"description": "Drivers such as sql_alchemy supports only one catalog at a time. So specific catalog name must be provided in order to use. The user should replace {catalogName} with the catalog desired.",
"value": {
"SQL_ALCHEMY": "peaka://dbc.peaka.studio:4567/{catalogName}?http_scheme=https&extra_credential=[[\"peakaKey\",\"gk4aUnCO.IYxkP1NxP67YkVViqYGZd4INpUAr04TE\"]]&access_token=true"
}
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/metadata/{projectId}": {
"get": {
"tags": [
"Data -- Metadata"
],
"summary": "Get Project Metadata",
"operationId": "getProjectMetadata",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "catalogId",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "schemaName",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/metadata/{projectId}/categorical/{catalogId}/{schemaName}/{tableName}/{columnName}": {
"put": {
"tags": [
"Data -- Metadata"
],
"summary": "Generate categorical values from the column.",
"operationId": "generateCategoricalColumnValues",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "catalogId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "schemaName",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "tableName",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "columnName",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MetadataCategoricalColumnRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"delete": {
"tags": [
"Data -- Metadata"
],
"summary": "Delete categorical values from the column meta and remove the scheduled job",
"operationId": "deleteCategoricalColumnValues",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "catalogId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "schemaName",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "tableName",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "columnName",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/metadata/{projectId}/golden-sql/query": {
"get": {
"tags": [
"Data -- Metadata"
],
"summary": "Semantic query golden sqls for the project.",
"operationId": "queryGoldenSqls",
"parameters": [
{
"name": "q",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/metadata/{projectId}/golden-sqls": {
"get": {
"tags": [
"Data -- Metadata"
],
"summary": "List of golden sqls for the project.",
"operationId": "listGoldenSqls",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"post": {
"tags": [
"Data -- Metadata"
],
"summary": "Create golden sql for the project",
"operationId": "addGoldenSql",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MetadataAddGoldenSqlRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/metadata/{projectId}/golden-sqls/{id}": {
"delete": {
"tags": [
"Data -- Metadata"
],
"summary": "Delete golden sql from the project.",
"operationId": "deleteGoldenSql",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/metadata/{projectId}/query": {
"get": {
"tags": [
"Data -- Metadata"
],
"summary": "Semantic query metadata for the project.",
"operationId": "queryMetadata",
"parameters": [
{
"name": "table",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "topK",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/metadata/{projectId}/questions/generate": {
"get": {
"tags": [
"Data -- Metadata"
],
"summary": "Generate sample ai questions for the project",
"operationId": "generateSampleQuestions",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "question",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/metadata/{projectId}/refresh": {
"post": {
"tags": [
"Data -- Metadata"
],
"summary": "Refresh Project Metadata",
"operationId": "refreshMetadata",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MetadataRefreshMetadataRequest"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/metadata/{projectId}/refresh/callback": {
"get": {
"tags": [
"Data -- Metadata"
],
"summary": "Get Metadata Refresh Job Callback",
"operationId": "getMetadataRefreshCallback",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"post": {
"tags": [
"Data -- Metadata"
],
"summary": "Register Metadata Refresh Job Callback",
"operationId": "registerMetadatRefreshCallback",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MetadataRefreshMetadataCallbackRequest"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"delete": {
"tags": [
"Data -- Metadata"
],
"summary": "Unregister Metadata Refresh Job Callback",
"operationId": "unRegisterMetadatRefreshCallback",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/metadata/{projectId}/refresh/{catalogId}": {
"get": {
"tags": [
"Data -- Metadata"
],
"summary": "Get Metadata Refresh Job Status",
"operationId": "getRefreshMetadataJobStatus",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "catalogId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Get Metadata Refresh Job Status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MetadataRefreshJobStatusResult"
},
"examples": {
"Get Metadata Refresh Job Response Example": {
"description": "Get Metadata Refresh Job Response Example",
"value": " {\n \"status\": \"active\" // Possible values: active, not-active,completed, waiting, delayed, failed, paused, stuck\n }\n"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/metadata/{projectId}/relations/{catalogId}": {
"get": {
"tags": [
"Data -- Metadata"
],
"summary": "Get Project Catalog Metadata Relations",
"operationId": "getProjectCatalogMetadataRelations",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "catalogId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/metadata/{projectId}/relations/{catalogId}/{schemaName}/{tableName}/{columnName}": {
"post": {
"tags": [
"Data -- Metadata"
],
"summary": "Add Relation To Metadata",
"operationId": "addRelation",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "catalogId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "schemaName",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "tableName",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "columnName",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MetadataAddRelationRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/metadata/{projectId}/relations/{catalogId}/{schemaName}/{tableName}/{relationId}": {
"put": {
"tags": [
"Data -- Metadata"
],
"summary": "Update Relation From Metadata",
"operationId": "updateRelation",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "catalogId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "schemaName",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "tableName",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "relationId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MetadataUpdateRelationRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"delete": {
"tags": [
"Data -- Metadata"
],
"summary": "Delete Relation From Metadata",
"operationId": "deleteRelation",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "catalogId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "schemaName",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "tableName",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "relationId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/metadata/{projectId}/semantics/{catalogId}/{schemaName}/{tableName}": {
"post": {
"tags": [
"Data -- Metadata"
],
"summary": "Generate semantics for the table",
"operationId": "generateSemantics",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "catalogId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "schemaName",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "tableName",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MetadataCreateSemanticsRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/metadata/{projectId}/{catalogId}": {
"put": {
"tags": [
"Data -- Metadata"
],
"summary": "Update Metadata ai usage per catalog level",
"operationId": "updateMetadataWithCatalogId",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "catalogId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MetadataAIUsageUpdateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/metadata/{projectId}/{catalogId}/{schemaName}": {
"put": {
"tags": [
"Data -- Metadata"
],
"summary": "Update Metadata ai usage per schema level",
"operationId": "updateMetadataWithCatalogIdAndSchemaName",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "catalogId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "schemaName",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MetadataAIUsageUpdateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/metadata/{projectId}/{catalogId}/{schemaName}/{tableName}": {
"put": {
"tags": [
"Data -- Metadata"
],
"summary": "Update Metadata",
"operationId": "updateMetadata",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "catalogId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "schemaName",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "tableName",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MetadataUpdateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/ai-agent/workflow/png": {
"get": {
"tags": [
"AI -- AgentV2"
],
"summary": "Get png image of current ai workflow",
"operationId": "getWorkflowImage",
"responses": {
"200": {
"description": "OK",
"content": {
"image/png": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/ai-agent/{projectId}/chat": {
"post": {
"tags": [
"AI -- AgentV2"
],
"summary": "Chat with agent",
"operationId": "chat",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AIAgentChatRequestDto"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/ai-agent/{projectId}/chat/stream": {
"post": {
"tags": [
"AI -- AgentV2"
],
"summary": "Chat with agent via stream",
"operationId": "chatStream",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AIAgentChatStreamRequestDto"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"text/event-stream": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ServerSentEventMapStringObject"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/ai-agent/{projectId}/threads": {
"get": {
"tags": [
"AI -- AgentV2"
],
"summary": "List ai-agent threads",
"operationId": "listThreads",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/ai-agent/{projectId}/threads/{threadId}": {
"get": {
"tags": [
"AI -- AgentV2"
],
"summary": "Get ai-agent thread",
"operationId": "getThread",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "threadId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"put": {
"tags": [
"AI -- AgentV2"
],
"summary": "Update ai-agent thread display name",
"operationId": "updateThread",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "threadId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AIAgentThreadUpdateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
},
"delete": {
"tags": [
"AI -- AgentV2"
],
"summary": "Delete ai-agent thread",
"operationId": "deleteThread",
"parameters": [
{
"name": "projectId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "threadId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "object"
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/sql/transpile/{dialect}": {
"post": {
"tags": [
"Data -- SQL"
],
"summary": "Transpile SQL",
"description": "Transpiles a SQL query from Peaka's SQL dialect (Trino) into the specified target dialect (e.g., mysql, postgres, bigquery). Useful when you need to export or reuse queries written in Peaka in other database systems.",
"operationId": "transpileSQL",
"parameters": [
{
"name": "dialect",
"in": "path",
"description": "Target SQL dialect to transpile into",
"required": true,
"schema": {
"type": "string"
},
"example": "mysql"
}
],
"requestBody": {
"description": "SQL query to transpile",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SQLTranspileQueryRequest"
},
"examples": {
"Transpile Query Example": {
"description": "Transpile Query Example",
"value": {
"query": "SELECT * FROM catalog.schema.table WHERE id = 1"
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Transpiled query",
"content": {
"application/json": {
"examples": {
"Transpiled Result": {
"description": "Transpiled Result",
"value": {
"result": "SELECT * FROM `catalog`.`schema`.`table` WHERE `id` = 1"
}
}
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/materialized-queries/status": {
"get": {
"tags": [
"Data -- Materialized Queries"
],
"summary": "List Materialized Query Statuses",
"description": "Returns refresh status and schedule information for all materialized queries in the project.",
"operationId": "listMaterializedQueryStatuses",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
}
],
"responses": {
"200": {
"description": "List of materialized query statuses",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MaterializedQueryStatusView"
}
},
"example": [
{
"queryId": "709922802836177297",
"queryName": "samplequery",
"scheduleSettings": {
"cronExpression": null,
"repeatDuration": "PT6H",
"timezone": null,
"type": "interval"
},
"nextExecutionStartTime": "2025-01-15T16:00:00Z",
"status": "COMPLETED",
"lastExecutionStartTime": "2025-01-15T10:00:00Z",
"lastUpdateTime": "2025-01-15T10:05:00Z"
}
]
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/materialized-queries/{queryId}/cancel": {
"post": {
"tags": [
"Data -- Materialized Queries"
],
"summary": "Cancel Materialized Query Refresh",
"description": "Cancels the in-progress refresh of a materialized query, if any.",
"operationId": "cancelMaterializedQuery",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "queryId",
"in": "path",
"description": "ID of the Query",
"required": true,
"schema": {
"type": "string"
},
"example": 709922802836177300
}
],
"responses": {
"200": {
"description": "Cancel request accepted"
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/materialized-queries/{queryId}/refresh": {
"post": {
"tags": [
"Data -- Materialized Queries"
],
"summary": "Refresh Materialized Query",
"description": "Triggers an immediate refresh of a materialized query. If the query has an existing schedule, the scheduled workflow is invoked; otherwise a one-time refresh is started.",
"operationId": "refreshMaterializedQuery",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "queryId",
"in": "path",
"description": "ID of the Query",
"required": true,
"schema": {
"type": "string"
},
"example": 709922802836177300
}
],
"responses": {
"200": {
"description": "Refresh request accepted"
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
},
"/data/projects/{projectId}/materialized-queries/{queryId}/status": {
"get": {
"tags": [
"Data -- Materialized Queries"
],
"summary": "Read Materialized Query Status",
"description": "Returns refresh status and schedule information for a single materialized query.",
"operationId": "readMaterializedQueryStatus",
"parameters": [
{
"name": "projectId",
"in": "path",
"description": "ID of the Project",
"required": true,
"schema": {
"type": "string"
},
"example": "mtKDhe1U"
},
{
"name": "queryId",
"in": "path",
"description": "ID of the Query",
"required": true,
"schema": {
"type": "string"
},
"example": 709922802836177300
}
],
"responses": {
"200": {
"description": "Materialized query status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MaterializedQueryStatusView"
},
"example": {
"queryId": "709922802836177297",
"queryName": "samplequery",
"scheduleSettings": {
"cronExpression": null,
"repeatDuration": "PT6H",
"timezone": null,
"type": "interval"
},
"nextExecutionStartTime": "2025-01-15T16:00:00Z",
"status": "COMPLETED",
"lastExecutionStartTime": "2025-01-15T10:00:00Z",
"lastUpdateTime": "2025-01-15T10:05:00Z"
}
}
}
}
},
"x-mint": {
"content": "\n \n \n\n"
}
}
}
},
"components": {
"schemas": {
"ProjectRequest": {
"required": [
"name"
],
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Project name",
"example": "My Project"
},
"description": {
"type": "string",
"description": "Descriptive text about the project",
"example": "This is a project that does something"
}
}
},
"Project": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Project ID"
},
"name": {
"type": "string",
"description": "Project name"
},
"description": {
"type": "string",
"description": "Descriptive text about the project"
},
"domain": {
"type": "string",
"description": "Domain of the project"
},
"webhookBaseUrl": {
"type": "string",
"description": "Webhook base URL"
},
"createdAt": {
"type": "string",
"description": "The date and time the project was created"
},
"owner": {
"type": "string",
"description": "The owner of the project"
},
"workspaceId": {
"type": "string",
"description": "The workspace to which the project belongs"
}
},
"description": "Project"
},
"WorkspaceRequest": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the workspace"
},
"description": {
"type": "string",
"description": "Descriptive text about the workspace"
}
}
},
"Workspace": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The unique identifier of the workspace",
"format": "uuid"
},
"name": {
"type": "string",
"description": "The name of the workspace"
},
"createdBy": {
"type": "string",
"description": "The unique identifier of the user who created the workspace",
"format": "uuid"
},
"organizationId": {
"type": "string",
"description": "The unique identifier of the organization to which the workspace belongs",
"format": "uuid"
},
"description": {
"type": "string",
"description": "Descriptive text about the workspace"
},
"createdAt": {
"type": "string",
"description": "The date and time the workspace was created"
},
"defaultWorkspace": {
"type": "boolean",
"description": "Whether the workspace is the default workspace for the organization.\n\n\n This is a backward compatibility field in order to create projects in the default workspace if the workspace is not specified."
}
}
},
"MetadataAIUsageUpdateRequest": {
"type": "object",
"properties": {
"useWithAI": {
"type": "boolean"
}
}
},
"MetadataColumn": {
"type": "object",
"properties": {
"columnName": {
"type": "string"
},
"columnDescription": {
"type": "string"
},
"dataType": {
"type": "string"
},
"order": {
"type": "integer",
"format": "int32"
},
"isNotNull": {
"type": "boolean"
},
"isSystem": {
"type": "boolean"
},
"isUnique": {
"type": "boolean"
},
"isPrimary": {
"type": "boolean"
},
"isCategorical": {
"type": "boolean"
},
"categoricalValues": {
"type": "array",
"items": {
"type": "string"
}
},
"lineage": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MetadataColumnLineage"
}
}
}
},
"MetadataColumnLineage": {
"type": "object",
"properties": {
"tables": {
"type": "array",
"items": {
"type": "string"
}
},
"column": {
"type": "string"
},
"expression": {
"type": "string"
}
}
},
"MetadataUpdateRequest": {
"type": "object",
"properties": {
"tableDescription": {
"type": "string"
},
"columns": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MetadataColumn"
}
},
"useWithAI": {
"type": "boolean"
}
}
},
"MetadataUpdateRelationRequest": {
"type": "object",
"properties": {
"type": {
"type": "string"
}
}
},
"MetadataCategoricalColumnRequest": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"format": "int32"
},
"frequency": {
"type": "string"
}
}
},
"ColumnRequest": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the column."
},
"dataType": {
"type": "string",
"description": "The data type of the column.",
"enum": [
"VARCHAR",
"BIGINT",
"BOOLEAN",
"DECIMAL",
"TIMESTAMP",
"TIME",
"DATE",
"UUID"
]
},
"displayName": {
"type": "string",
"description": "The display name of the column."
},
"defaultValue": {
"type": "string",
"description": "The default value of the column."
},
"isNotNull": {
"type": "boolean",
"description": "The not null flag for the column."
},
"isUnique": {
"type": "boolean",
"description": "The unique flag for the column."
}
},
"description": "ColumnRequest is used to create, update, display a column in a table.\n It contains the name, data type, display name, default value, not null and unique status of the column request."
},
"ColumnDetail": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The id of the column."
},
"name": {
"type": "string",
"description": "The name of the column."
},
"dataType": {
"type": "string",
"description": "The data type of the column."
},
"displayName": {
"type": "string",
"description": "The display name of the column."
},
"defaultValue": {
"type": "string",
"description": "The default value of the column."
},
"isNotNull": {
"type": "boolean",
"description": "The not null flag for the column."
},
"isUnique": {
"type": "boolean",
"description": "The unique flag for the column."
},
"desc": {
"type": "string",
"description": "The description of the column."
}
}
},
"MaterializedQuerySchedule": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Type of schedule.",
"enum": [
"interval",
"cron",
"none"
]
},
"cronExpression": {
"type": "string",
"description": "UNIX cron expression (minute hour day-of-month month day-of-week), e.g. '0 0 * * *' for every day at midnight. Set only when the schedule type is 'cron'.",
"nullable": true,
"example": "0 0 * * *"
},
"repeatDuration": {
"type": "string",
"description": "ISO-8601 duration between refreshes, e.g. 'PT6H' (every 6 hours), 'PT12H' (twice daily), 'P1D' (daily). Set only when the schedule type is 'interval'.",
"nullable": true,
"example": "PT12H"
},
"timezone": {
"type": "string",
"description": "IANA timezone used to evaluate the cron expression, e.g. 'UTC' or 'Europe/Istanbul'. Set only when the schedule type is 'cron'.",
"nullable": true,
"example": "UTC"
}
},
"description": "Schedule configuration of a materialized query. Provide EITHER an interval schedule (`type=interval` with `repeatDuration`) OR a cron schedule (`type=cron` with `cronExpression` and optional `timezone`). Use `type=none` for no schedule. The fields that do not apply to the chosen type are omitted.",
"nullable": true,
"example": {
"type": "cron",
"cronExpression": "0 0 * * *",
"timezone": "UTC"
}
},
"QueryRequest": {
"type": "object",
"properties": {
"displayName": {
"type": "string",
"description": "The display name of the query.",
"example": "sampleQuery"
},
"inputQuery": {
"type": "string",
"description": "The SQL query. Required unless inputQueryRefId is provided.",
"nullable": true
},
"queryType": {
"type": "string",
"description": "The type of the query. Defaults to PLAIN.",
"default": "PLAIN",
"enum": [
"PLAIN",
"MATERIALIZED"
]
},
"schedule": {
"$ref": "#/components/schemas/MaterializedQuerySchedule"
},
"inputQueryRefId": {
"type": "string",
"description": "The id of an existing query to materialize. Valid only if the query type is MATERIALIZED. When set, the materialized query is built from the referenced query's SQL and inputQuery is not required. The reference is resolved when the request is processed: a snapshot of the referenced query's SQL is stored as this query's inputQuery. The reference id itself is not persisted and is not returned in responses; later changes to the referenced query do not propagate. Send the reference again on an update to re-resolve from the source.",
"nullable": true,
"example": "709922802836177297"
},
"path": {
"type": "string",
"description": "The folder path to place this query in. Intermediate folders are created automatically. If omitted, the query is placed at the root level.",
"nullable": true,
"example": "/reports/monthly"
}
}
},
"Query": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the query."
},
"displayName": {
"type": "string",
"description": "The display name of the query."
},
"name": {
"type": "string",
"description": "The name of the query used in SQL, e.g. SELECT * FROM \"peaka\".\"query\".\"Both lists are initialised to empty {@link ArrayList ArrayList}s so the serialised\n JSON always contains "queryIdsAdded": [...] and\n "queryIdsRemoved": [...]. The search service requires both fields\n to be present (non-null) and rejects null with a validation error."
},
"QueryFolderItem": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the folder (UUID)",
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"name": {
"type": "string",
"description": "Display name of the folder",
"example": "Monthly Reports"
},
"path": {
"type": "string",
"description": "Full path of the folder in the hierarchy",
"example": "/reports/monthly"
},
"parentId": {
"type": "string",
"description": "ID of the parent folder, null if root-level",
"example": "550e8400-e29b-41d4-a716-446655440001"
},
"createdAt": {
"type": "string",
"description": "Timestamp when the folder was created (ISO 8601)",
"example": "2025-01-15T10:30:00Z"
}
},
"description": "Represents a query folder"
},
"QueryFolderWithContentsResponse": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the folder (UUID)"
},
"name": {
"type": "string",
"description": "Display name of the folder"
},
"path": {
"type": "string",
"description": "Full path of the folder in the hierarchy"
},
"parentId": {
"type": "string",
"description": "ID of the parent folder, null if root-level"
},
"createdAt": {
"type": "string",
"description": "Timestamp when the folder was created (ISO 8601)"
},
"folders": {
"type": "array",
"description": "Direct child folders",
"items": {
"$ref": "#/components/schemas/QueryFolderItem"
}
},
"queries": {
"type": "array",
"description": "Queries contained in this folder",
"items": {
"$ref": "#/components/schemas/Query"
}
}
},
"description": "A folder with its direct child folders and queries"
},
"CacheSettingsUpdateRequest": {
"type": "object",
"properties": {
"incrementalCacheSchedule": {
"$ref": "#/components/schemas/Schedule"
},
"fullRefreshCacheSchedule": {
"$ref": "#/components/schemas/Schedule"
}
},
"description": "This class represents a request to cache data.\n It contains the catalog ID, schema name, table name, and schedule of the cache request."
},
"Schedule": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The type of the schedule. BASIC or NONE."
},
"expression": {
"type": "string",
"description": "The expression of the schedule.\n Valid if the type is other than NONE.\n For BASIC, the expression is a duration in ISO-8601 format.\n \"PT15M\" -- parses as \"15 minutes\" (where a minute is 60 seconds)\n \"PT10H\" -- parses as \"10 hours\" (where an hour is 3600 seconds)\n \"P2D\" -- parses as \"2 days\" (where a day is 24 hours or 86400 seconds)"
}
},
"description": "This class represents a schedule for a cache request.\n It contains the type and expression of the schedule."
},
"Cache": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the cache."
},
"catalogId": {
"type": "string",
"description": "The ID of the catalog for the cache request."
},
"schemaName": {
"type": "string",
"description": "The name of the schema for the cache request."
},
"tableName": {
"type": "string",
"description": "The name of the table for the cache request."
},
"incrementalCacheSchedule": {
"$ref": "#/components/schemas/Schedule"
},
"fullRefreshCacheSchedule": {
"$ref": "#/components/schemas/Schedule"
},
"appId": {
"type": "string",
"writeOnly": true
},
"projectId": {
"type": "string",
"description": "The ID of the project for the cache request."
}
}
},
"ConnectionRequest": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the connection given by the user"
},
"type": {
"type": "string",
"description": "Type of connection.\n \n Example: airtable for AirTable, stripe for Stripe, hubspot_access_token for HubSpot (with Access Token), etc.\n\n Exact list can be fetched by following url: /connections/config"
},
"credential": {
"type": "object",
"additionalProperties": true,
"description": "Credential object for the connection.\n\nIts structure is dependent on the connection type and can be fetched by following url: /connections/config\n"
},
"connectionCallback": {
"type": "string",
"description": "The url to redirect to after an oauth connection is established."
}
}
},
"Connection": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Connection ID"
},
"name": {
"type": "string",
"description": "Name of the connection"
},
"type": {
"type": "string",
"description": "Type of connection.\n\nExample: airtable for AirTable, stripe for Stripe, hubspot_access_token for HubSpot (with Access Token), etc.\n\nExact list can be fetched by following url: /connections/config\n"
},
"url": {
"type": "string",
"description": "Oauth callback url if the connection is Oauth based.\n"
}
}
},
"AIAgentThreadUpdateRequest": {
"type": "object",
"properties": {
"displayName": {
"type": "string",
"description": "The new name for the AI chat thread."
}
}
},
"InitSessionRequest": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "The project ID."
},
"theme": {
"type": "string",
"description": "The theme to be used."
},
"sessionMode": {
"type": "string",
"description": "The session mode, determining the type of session to be initialized.",
"enum": [
"CONNECTOR_MODAL_ONLY",
"FULL_STUDIO"
]
},
"themeOverride": {
"type": "boolean",
"description": "Flag indicating whether the theme should be overridden."
},
"timeoutInSeconds": {
"type": "integer",
"description": "The timeout duration in seconds.",
"format": "int32"
}
},
"discriminator": {
"propertyName": "sessionMode"
}
},
"EmbeddedSession": {
"type": "object",
"properties": {
"sessionUrl": {
"type": "string",
"description": "The URL of the Embedded Peaka session to be followed.\n\nIt is a one-time use URL that will redirect the user to the Peaka session.\n"
},
"partnerOrigin": {
"type": "string",
"description": "The origin of the partner that the embedded studio is coming from.\n"
}
}
},
"SQLTranspileQueryRequest": {
"type": "object",
"properties": {
"query": {
"type": "string"
}
}
},
"ApiKeyRequest": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the API key"
},
"expiresAt": {
"type": "string",
"description": "The expiration date and time of the API key in ISO-8601 format (e.g., \"2025-12-31T23:59:59Z\").\n If not provided, the API key will not have an expiration date.\n The time should be in the ISO-8601 standard.",
"format": "date-time"
}
}
},
"ApiKey": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the API key"
},
"apiKey": {
"type": "string",
"description": "API key. It is a secret and should not be shared. Please store it securely. You will not be able to see it again."
},
"apiKeyId": {
"type": "string",
"description": "ID of the API key",
"format": "uuid"
},
"expiresAt": {
"type": "string",
"description": "Expiration date of the API key. If null, the API key never expires.\n The time is in the ISO-8601 standard.",
"format": "date-time"
}
},
"description": "Represents an API key."
},
"MetadataCreateSemanticsRequest": {
"type": "object",
"properties": {
"threadId": {
"type": "string"
},
"initialPrompt": {
"type": "string"
},
"limit": {
"type": "integer",
"format": "int32"
}
}
},
"MetadataAddRelationRequest": {
"type": "object",
"properties": {
"targetCatalogId": {
"type": "string"
},
"targetSchemaName": {
"type": "string"
},
"targetTableName": {
"type": "string"
},
"targetColumnName": {
"type": "string"
},
"type": {
"type": "string"
}
}
},
"MetadataRefreshMetadataRequest": {
"type": "object",
"properties": {
"catalogId": {
"type": "string"
},
"callbackURL": {
"type": "string"
},
"callbackToken": {
"type": "string"
}
}
},
"MetadataRefreshMetadataCallbackRequest": {
"type": "object",
"properties": {
"callbackURL": {
"type": "string"
},
"callbackToken": {
"type": "string"
}
}
},
"MetadataAddGoldenSqlRequest": {
"type": "object",
"properties": {
"prompt": {
"type": "string"
},
"sql": {
"type": "string"
}
}
},
"Table": {
"type": "object",
"properties": {
"catalogId": {
"type": "string",
"description": "The ID of the catalog that the table belongs to."
},
"catalogName": {
"type": "string",
"description": "The name of the catalog that the table belongs to."
},
"schemaName": {
"type": "string",
"description": "The name of the schema that the table belongs to."
},
"tableName": {
"type": "string",
"description": "The name of the table."
},
"supportedCacheTypes": {
"type": "array",
"description": "The cache types supported by the table: FULL_REFRESH and/or INCREMENTAL.\n An empty list means the table is not cacheable.\n The field is absent when capability information could not be resolved.",
"items": {
"type": "string"
}
},
"isCacheable": {
"type": "boolean",
"description": "Indicates whether the table is cacheable or not."
},
"isDynamicTable": {
"type": "boolean",
"description": "Indicates whether the table has required query parameter columns or not.\n A query parameter column is prefixed with \"_q_\" e.g. \"_q_date\".\n These columns are used to filter the data in the table."
},
"isCached": {
"type": "boolean",
"description": "Indicates whether the table is cached or not.\n It is not the status of caching.\n
\n e.g. when a table is cached, you are no longer accessing the original data source.\n But the data may not be complete since an ongoing cache refresh is in progress."
}
},
"description": "Represents a table in a schema."
},
"ImportJob": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"startTime": {
"type": "integer",
"format": "int64"
},
"endTime": {
"type": "integer",
"format": "int64"
},
"progress": {
"type": "integer",
"format": "int32"
},
"result": {
"type": "object",
"additionalProperties": true
}
}
},
"SemanticCatalogRequest": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the catalog"
}
}
},
"Catalog": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the catalog."
},
"name": {
"type": "string",
"description": "The name of the catalog."
},
"displayName": {
"type": "string",
"description": "The display name of the catalog."
},
"catalogType": {
"type": "string",
"description": "The type of the catalog."
},
"connectionId": {
"type": "string",
"description": "The connection ID of the catalog."
}
},
"description": "This class represents a Catalog.\n It contains the id, name, display name, type, and connection ID of the catalog."
},
"SemanticTableRequest": {
"type": "object",
"properties": {
"schemaName": {
"type": "string",
"description": "The name of the schema."
},
"tableName": {
"type": "string",
"description": "The name of the table."
},
"queryId": {
"type": "string",
"description": "The ID of the query which is used to populate the semantic table."
}
}
},
"SemanticTable": {
"type": "object",
"properties": {
"catalogId": {
"type": "string",
"description": "The ID of the catalog that the table belongs to."
},
"catalogName": {
"type": "string",
"description": "The name of the catalog that the table belongs to."
},
"schemaName": {
"type": "string",
"description": "The name of the schema that the table belongs to."
},
"tableName": {
"type": "string",
"description": "The name of the table."
},
"tableId": {
"type": "string",
"description": "The ID of the semantic table."
}
},
"description": "Represents a table in a schema."
},
"CatalogShareRequest": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "Target Project ID"
}
}
},
"SearchRequest": {
"type": "object",
"properties": {
"catalog": {
"type": "string",
"description": "Catalog Query Name. Search only for that catalog."
},
"schema": {
"type": "string",
"description": "Schema Name. Search only for that schema. If catalog is also given, find the tables under catalog.schema.*"
},
"query": {
"type": "string",
"description": "Search term. Does a case-insensitive contains search."
},
"limit": {
"type": "integer",
"description": "Number of results to return. Default is 100.",
"format": "int32"
},
"offset": {
"type": "integer",
"description": "Number of results to skip. Default is 0.",
"format": "int32"
}
}
},
"CatalogSchemaTable": {
"type": "object",
"properties": {
"catalog": {
"type": "string",
"description": "Catalog Query Name"
},
"schema": {
"type": "string",
"description": "Schema Name"
},
"table": {
"type": "string",
"description": "Table Name"
}
}
},
"Meta": {
"type": "object",
"properties": {
"page": {
"$ref": "#/components/schemas/Page"
},
"query": {
"$ref": "#/components/schemas/Query"
}
}
},
"Page": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"format": "int32"
},
"offset": {
"type": "integer",
"format": "int32"
},
"nextOffset": {
"type": "integer",
"format": "int32"
}
}
},
"SearchResult": {
"type": "object",
"properties": {
"matchedCatalogs": {
"type": "array",
"description": "Catalogs matched.",
"items": {
"$ref": "#/components/schemas/CatalogSchemaTable"
}
},
"matchedSchemas": {
"type": "array",
"description": "Schemas matched.",
"items": {
"$ref": "#/components/schemas/CatalogSchemaTable"
}
},
"matchedTables": {
"type": "array",
"description": "Tables matched.",
"items": {
"$ref": "#/components/schemas/CatalogSchemaTable"
}
},
"meta": {
"$ref": "#/components/schemas/Meta"
}
}
},
"ExportCsvOptions": {
"type": "object",
"properties": {
"delimiter": {
"type": "string",
"description": "Field delimiter",
"example": ",",
"default": ","
},
"quoteChar": {
"type": "string",
"description": "Quote character",
"example": "\"",
"default": "\""
},
"recordSeparator": {
"type": "string",
"description": "Record separator",
"example": "\\n",
"default": "\\n"
},
"includeHeader": {
"type": "boolean",
"description": "Whether to emit a header row",
"example": true,
"default": true
},
"nullValue": {
"type": "string",
"description": "Representation of NULL values"
}
},
"description": "CSV formatting options (ignored for JSONL exports)"
},
"ExportRequest": {
"type": "object",
"properties": {
"format": {
"type": "string",
"description": "Output format",
"example": "CSV",
"default": "CSV",
"enum": [
"CSV",
"JSONL"
]
},
"limit": {
"type": "integer",
"description": "Row limit; clamped to [1, 1000000]",
"format": "int32",
"example": 100000
},
"csvOptions": {
"$ref": "#/components/schemas/ExportCsvOptions"
},
"includeSystemColumns": {
"type": "boolean",
"description": "When false, Peaka system columns (_id, _version, …) are excluded. Cache plumbing columns (_q_*, _cache_*) are always dropped.",
"example": true,
"default": true
},
"columns": {
"type": "array",
"description": "Explicit column selection; an unknown name yields 400. Omit to export all columns.",
"example": [
"id",
"created",
"amount"
],
"items": {
"type": "string",
"description": "Explicit column selection; an unknown name yields 400. Omit to export all columns.",
"example": "[\"id\",\"created\",\"amount\"]"
}
},
"compression": {
"type": "string",
"description": "Output compression; with GZIP every artifact is a gzip stream carrying a .gz suffix",
"example": "NONE",
"default": "NONE",
"enum": [
"NONE",
"GZIP"
]
}
},
"description": "Async export request. The job is accepted (202) and runs in the background; the result is downloaded via presigned URLs returned by the status endpoint."
},
"ExportJobCreated": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Export job id",
"example": "4c9fcb44-126a-45f8-99a0-f1d245083d78"
},
"status": {
"type": "string",
"description": "Initial job status",
"example": "PENDING"
}
},
"description": "Acknowledgement returned when an export job is accepted"
},
"QueryFolderCreateRequest": {
"type": "object",
"properties": {
"folderName": {
"type": "string"
}
}
},
"QueryExecuteRequest": {
"type": "object",
"properties": {
"columns": {
"type": "array",
"description": "Columns to select. If omitted, all columns (*) are returned.",
"items": {
"type": "string"
}
},
"from": {
"type": "array",
"description": "Tables to query from. At least one entry is required.",
"items": {
"$ref": "#/components/schemas/TableForQuery"
}
},
"limit": {
"type": "integer",
"description": "Maximum number of rows to return.",
"format": "int64"
},
"offset": {
"type": "integer",
"description": "Number of rows to skip before returning results.",
"format": "int64"
},
"orderBy": {
"type": "array",
"description": "Ordering specifications. Each entry is a column name optionally followed by ASC or DESC.\n Example: ["amount DESC", "created_at ASC"].",
"items": {
"type": "string"
}
},
"filters": {
"type": "object",
"additionalProperties": true,
"description": "Filter conditions. Supports and/or logic with column comparisons."
},
"timeout": {
"type": "integer",
"description": "Query timeout in seconds.",
"format": "int32"
}
},
"description": "Executes a query using the query builder. The from field is required.\n\n
Minimal example:\n
\n {\n \"from\": [\n {\n \"catalogName\": \"peaka\",\n \"schemaName\": \"query\",\n \"tableName\": \"samplequery\"\n }\n ]\n }\n \n\n With columns, filters, limit, offset, and orderBy:\n
\n {\n \"columns\": [\"amount\"],\n \"from\": [\n {\n \"catalogName\": \"wilderman_green\",\n \"schemaName\": \"payment\",\n \"tableName\": \"charges\"\n }\n ],\n \"filters\": {\n \"and\": [\n [\n { \"column\": { \"catalogName\": \"wilderman_green\", \"schemaName\": \"payment\", \"tableName\": \"charges\", \"columnName\": \"amount\" } },\n \">\",\n [150]\n ]\n ]\n },\n \"limit\": 50,\n \"offset\": 0,\n \"orderBy\": [\"amount DESC\"]\n }\n "
},
"TableForQuery": {
"type": "object",
"properties": {
"catalogId": {
"type": "string"
},
"catalogName": {
"type": "string"
},
"schemaName": {
"type": "string"
},
"tableName": {
"type": "string"
}
}
},
"QueryExecuteRequestId": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the query to execute."
},
"timeout": {
"type": "integer",
"description": "Query timeout in seconds.",
"format": "int32"
}
},
"description": "Executes a query by its ID.\n\n \n {\n \"id\": \"709922802836177297\"\n\n }\n "
},
"QueryExecuteRequestName": {
"type": "object",
"properties": {
"qualifiedName": {
"type": "string",
"description": "Fully qualified name of the query, e.g.\n peaka.query.samplequery or\n peaka.mtquery.samplequery or\n stripe.payment.charges"
},
"timeout": {
"type": "integer",
"description": "Query timeout in seconds.",
"format": "int32"
}
},
"description": "Executes a query by its fully qualified name in the format <catalogName>.<schemaName>.<tableName>.\n\n \n {\"qualifiedName\": \"peaka.query.samplequery\"}\n "
},
"QueryExecuteRequestStatement": {
"type": "object",
"properties": {
"statement": {
"type": "string",
"description": "The SQL statement to execute."
},
"bindings": {
"type": "array",
"description": "Optional bind arguments for parameterised queries.",
"items": {
"type": "string"
}
},
"timeout": {
"type": "integer",
"description": "Query timeout in seconds.",
"format": "int32"
}
},
"description": "Executes a raw SQL statement directly via the queries/execute endpoint.\n\n \n {\n \"statement\": \"SELECT * FROM \\\"peaka\\\".\\\"query\\\".\\\"samplequery\\\"\",\n \"bindArgs\": [\"arg1\", \"arg2\"]\n }\n "
},
"CatalogRequest": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the catalog"
},
"connectionId": {
"type": "string",
"description": "Connection ID.\n\nThis is the ID of the connection that is used to connect to the catalog.\n\nYou must create a connection before creating a catalog.\n"
},
"extraParameters": {
"type": "object",
"additionalProperties": true,
"description": "Extra parameters for the catalog"
}
}
},
"CatalogShareRequestV2": {
"type": "object",
"properties": {
"targetProjectId": {
"type": "string",
"description": "Target Project ID"
}
}
},
"SharedCatalogResponse": {
"type": "object",
"properties": {
"sharedCatalogId": {
"type": "string",
"description": "The ID of the shared catalog."
}
}
},
"ParametricTable": {
"type": "object",
"properties": {
"fromSchema": {
"type": "string",
"description": "Schema of the base table"
},
"fromTable": {
"type": "string",
"description": "Name of the base table"
},
"toSchema": {
"type": "string",
"description": "Schema of the target table"
},
"toTable": {
"type": "string",
"description": "Name of the target table"
},
"paramValues": {
"type": "array",
"description": "List of parametric columns",
"items": {
"$ref": "#/components/schemas/ParametricTableColumn"
}
}
}
},
"ParametricTableColumn": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Column name"
},
"value": {
"type": "object",
"description": "Column value"
}
},
"description": "Parametric table column"
},
"CacheRequest": {
"type": "object",
"properties": {
"catalogId": {
"type": "string",
"description": "The ID of the catalog for the cache request."
},
"schemaName": {
"type": "string",
"description": "The name of the schema for the cache request."
},
"tableName": {
"type": "string",
"description": "The name of the table for the cache request."
},
"incrementalCacheSchedule": {
"$ref": "#/components/schemas/Schedule"
},
"fullRefreshCacheSchedule": {
"$ref": "#/components/schemas/Schedule"
}
},
"description": "This class represents a request to cache data.\n It contains the catalog ID, schema name, table name, and schedule of the cache request."
},
"CacheCreateStatus": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"error": {
"type": "string"
},
"cache": {
"$ref": "#/components/schemas/Cache"
}
}
},
"Oauth2Callback": {
"type": "object",
"properties": {
"queryParameters": {
"type": "string",
"description": "Query parameters received from the Oauth2 redirection. Pass all query parameters as a single string.\n\n Example: \"https://yourdomain.com/oauth2/mycallback?code=1234&state=xyz¶m1=value1¶m2=value2\"\n\n \"queryParameters\": \"code=1234&state=xyz¶m1=value1¶m2=value2\""
}
}
},
"AIAgentChatRequestDto": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"threadId": {
"type": "string"
},
"noExecute": {
"type": "boolean"
}
}
},
"AIAgentChatStreamRequestDto": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"threadId": {
"type": "string"
},
"noExecute": {
"type": "boolean"
},
"streamModes": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"ServerSentEventMapStringObject": {
"type": "object"
},
"QueryPathUpdateRequest": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "The path to place this query in (e.g. \"/analytics/dashboards\")."
}
}
},
"QueryFolderRenameRequest": {
"required": [
"name"
],
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "New name for the folder",
"example": "Archived Reports"
}
},
"description": "Request body for renaming a query folder"
},
"Organization": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The unique identifier of the organization",
"format": "uuid"
},
"name": {
"type": "string",
"description": "The name of the organization"
},
"owner": {
"type": "string",
"description": "The unique identifier of the user who created the organization",
"format": "uuid"
},
"createdAt": {
"type": "string",
"description": "The date and time the organization was created"
},
"iconFileId": {
"type": "string",
"description": "The identifier of the file that contains the icon of the organization"
},
"description": {
"type": "string",
"description": "Descriptive text about the organization"
}
}
},
"MetadataRefreshJobStatusResult": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"NOT_ACTIVE",
"COMPLETED",
"WAITING",
"ACTIVE",
"DELAYED",
"FAILED",
"PAUSED",
"STUCK"
]
}
}
},
"QueryFolderListResponse": {
"type": "object",
"properties": {
"items": {
"type": "array",
"description": "List of folders in the project",
"items": {
"$ref": "#/components/schemas/QueryFolderItem"
}
}
},
"description": "Response containing a list of query folders"
},
"QueryFolderTreeNode": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the folder (UUID)"
},
"name": {
"type": "string",
"description": "Display name of the folder"
},
"path": {
"type": "string",
"description": "Full path of the folder"
},
"children": {
"type": "array",
"description": "Child folder nodes",
"items": {
"$ref": "#/components/schemas/QueryFolderTreeNode"
}
},
"queries": {
"type": "array",
"description": "Queries in this folder (present only when includeQueries=true)",
"items": {
"$ref": "#/components/schemas/Query"
}
}
},
"description": "A node in the folder tree hierarchy"
},
"QueryFolderTreeResponse": {
"type": "object",
"properties": {
"tree": {
"type": "array",
"description": "Root-level nodes of the folder tree",
"items": {
"$ref": "#/components/schemas/QueryFolderTreeNode"
}
}
},
"description": "Response containing the folder tree hierarchy"
},
"MaterializedQueryStatusView": {
"type": "object",
"properties": {
"queryId": {
"type": "string",
"description": "ID of the query",
"example": "709922802836177297"
},
"queryName": {
"type": "string",
"description": "Name of the query",
"example": "samplequery"
},
"scheduleSettings": {
"$ref": "#/components/schemas/MaterializedQuerySchedule"
},
"nextExecutionStartTime": {
"type": "string",
"description": "Next scheduled execution start time (ISO 8601). Null when the schedule type is 'none' or cannot be computed.",
"nullable": true,
"example": "2025-01-15T16:00:00Z"
},
"status": {
"type": "string",
"description": "Status of the most recent refresh",
"example": "COMPLETED"
},
"lastExecutionStartTime": {
"type": "string",
"description": "Start time of the last refresh (ISO 8601)",
"nullable": true,
"example": "2025-01-15T10:00:00Z"
},
"lastUpdateTime": {
"type": "string",
"description": "Time the status was last updated (ISO 8601)",
"nullable": true,
"example": "2025-01-15T10:05:00Z"
}
},
"description": "Status and schedule information for a materialized query"
},
"ExportFile": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "File name",
"example": "query_709922802836177297_charges.jsonl"
},
"url": {
"type": "string",
"description": "Presigned download URL (short-lived)",
"example": "https://