{"title":"Quest Agent API","summary":"Use trusted warehouse data to explain business changes, publish operating views, and automate follow-through in a Quest workspace.","version":"1","authentication":{"type":"bearer","header":"Authorization: Bearer <scoped-token>","authorization":"Start browser authorization at POST /v1/auth/device. A person signs in, compares the displayed code, selects a Workspace, and reviews the requested mode, exact scopes, Model policy, and lifetime before approval.","browserAuthorization":{"modes":{"explore":{"summary":"Inspect Workspace Files, context, catalog metadata, and approved materialized Model data without changing the Workspace.","hasOperationalEffects":false,"scopes":["workspace:read","context:read","catalog:read","query:preview","data:api"],"scopeDetails":[{"scope":"workspace:read","label":"View Workspace files","description":"List folders and read ordinary versioned files in the selected Workspace.","minimumRole":"viewer","category":"read"},{"scope":"context:read","label":"Read Workspace context","description":"Read bounded context about the Workspace, its files, Pages, and Actions.","minimumRole":"viewer","category":"read"},{"scope":"catalog:read","label":"Read the Data catalog","description":"Discover approved Sources, Models, and their metadata.","minimumRole":"viewer","category":"read"},{"scope":"query:preview","label":"Preview approved Data","description":"Read bounded preview rows from Data permitted by the model policy.","minimumRole":"viewer","category":"read"},{"scope":"data:api","label":"Query approved Data","description":"Run bounded queries against Data permitted by the model policy.","minimumRole":"viewer","category":"read"}]},"build":{"summary":"Explore, create and revise Workspace Files and Pages, and define Data without running operational effects.","hasOperationalEffects":false,"scopes":["workspace:read","context:read","catalog:read","query:preview","data:api","workspace:write","data:define"],"scopeDetails":[{"scope":"workspace:read","label":"View Workspace files","description":"List folders and read ordinary versioned files in the selected Workspace.","minimumRole":"viewer","category":"read"},{"scope":"context:read","label":"Read Workspace context","description":"Read bounded context about the Workspace, its files, Pages, and Actions.","minimumRole":"viewer","category":"read"},{"scope":"catalog:read","label":"Read the Data catalog","description":"Discover approved Sources, Models, and their metadata.","minimumRole":"viewer","category":"read"},{"scope":"query:preview","label":"Preview approved Data","description":"Read bounded preview rows from Data permitted by the model policy.","minimumRole":"viewer","category":"read"},{"scope":"data:api","label":"Query approved Data","description":"Run bounded queries against Data permitted by the model policy.","minimumRole":"viewer","category":"read"},{"scope":"workspace:write","label":"Create and revise Workspace files","description":"Write new file revisions with conflict checks, attribution, and audit history.","minimumRole":"editor","category":"author"},{"scope":"data:define","label":"Define Data","description":"Create or revise Source and Model definitions in the selected Workspace.","minimumRole":"editor","category":"author"}]},"operate":{"summary":"Build, manage connections, operate runs and automations, manage Tracking, and run governed Prospecting workflows.","hasOperationalEffects":true,"scopes":["workspace:read","context:read","catalog:read","query:preview","data:api","workspace:write","data:define","connections:read","connections:manage","runs:read","runs:operate","automations:manage","tracking:read","tracking:key:create","tracking:write","prospecting:read","prospecting:write","prospecting:reveal"],"scopeDetails":[{"scope":"workspace:read","label":"View Workspace files","description":"List folders and read ordinary versioned files in the selected Workspace.","minimumRole":"viewer","category":"read"},{"scope":"context:read","label":"Read Workspace context","description":"Read bounded context about the Workspace, its files, Pages, and Actions.","minimumRole":"viewer","category":"read"},{"scope":"catalog:read","label":"Read the Data catalog","description":"Discover approved Sources, Models, and their metadata.","minimumRole":"viewer","category":"read"},{"scope":"query:preview","label":"Preview approved Data","description":"Read bounded preview rows from Data permitted by the model policy.","minimumRole":"viewer","category":"read"},{"scope":"data:api","label":"Query approved Data","description":"Run bounded queries against Data permitted by the model policy.","minimumRole":"viewer","category":"read"},{"scope":"workspace:write","label":"Create and revise Workspace files","description":"Write new file revisions with conflict checks, attribution, and audit history.","minimumRole":"editor","category":"author"},{"scope":"data:define","label":"Define Data","description":"Create or revise Source and Model definitions in the selected Workspace.","minimumRole":"editor","category":"author"},{"scope":"connections:read","label":"View connections","description":"Inspect the Workspace's configured data and service connections.","minimumRole":"viewer","category":"operate"},{"scope":"connections:manage","label":"Manage connections","description":"Create, configure, and remove data or service connections.","minimumRole":"editor","category":"operate"},{"scope":"runs:read","label":"View runs","description":"Inspect Action run status, history, output, and errors.","minimumRole":"viewer","category":"operate"},{"scope":"runs:operate","label":"Operate runs","description":"Start and cancel Actions and other operational runs.","minimumRole":"editor","category":"operate"},{"scope":"automations:manage","label":"Manage automations","description":"Create, update, enable, disable, and remove schedules and webhooks.","minimumRole":"editor","category":"operate"},{"scope":"tracking:read","label":"View tracking configuration","description":"Inspect tracking databases, keys, configuration, and recent activity.","minimumRole":"viewer","category":"operate"},{"scope":"tracking:key:create","label":"Create tracking keys","description":"Issue new public or secret credentials that can ingest tracking events.","minimumRole":"editor","category":"operate"},{"scope":"tracking:write","label":"Manage tracking","description":"Configure tracking ingestion, retention, and session replay behavior.","minimumRole":"editor","category":"operate"},{"scope":"prospecting:read","label":"Search and view prospects","description":"Search companies and people, page search runs, and inspect Prospecting lists.","minimumRole":"viewer","category":"operate"},{"scope":"prospecting:write","label":"Manage prospect lists","description":"Create Prospecting lists, add records, and export selected records to Sources.","minimumRole":"editor","category":"operate"},{"scope":"prospecting:reveal","label":"Reveal prospect contact details","description":"Explicitly reveal business contact details for one identified person.","minimumRole":"editor","category":"operate"}]}},"modelPolicy":{"modelAccessMode":"all_materialized_models","allowedModelKeys":[],"summary":"The browser grant's Model policy covers all materialized Models in the selected Workspace; querying still requires an approved data scope. Raw Source rows, warehouse credentials, workspace secrets, and arbitrary SQL remain unavailable."},"sessionInspection":"GET /v1/session returns the approved scopes, Model policy, and scope-derived agentApiPermissions for the v1, Agent API, and Data API surfaces.","delegatedChat":"Starting a Quest Chat delegates analysis to another agent and is not included in explore, build, or operate. A person must grant chat:run separately in Settings when that delegation is intentional."},"requiredFor":"All workspace data, analysis, and changes","notRequiredFor":"This public guide"},"primitives":{"source":"Connected raw data used as evidence.","model":"A reusable SQL definition for a business metric or dataset.","page":"An operating view, report, dashboard, or workflow interface.","action":"An automation, monitor, schedule, webhook, or integration.","chat":"Durable analysis with its evidence and decision history."},"workflows":{"investigate_metric":["Load task-specific context.","Find the approved Model that defines the metric.","Quantify the largest drivers and supporting evidence.","Save repeatable analysis in a Page or Chat."],"publish_operating_view":["Inspect existing Pages and Models.","Build the smallest view that supports the decision.","Create or update the Page through an authorized v1 Files write and return its receipt, id, revision, and app link."],"automate_follow_through":["Define the signal, threshold, cadence or event, and responsible owner.","Create or update an Action that reads from an approved Model.","Return the Action and run ids, status, and how to stop it."],"run_durable_analysis":["Start a Chat run with the exact business question.","Keep the returned Chat and run ids.","Use those ids to inspect status or continue the analysis."]},"guidance":["Start from the user's business outcome.","Reuse existing Sources, Models, Pages, and Actions before creating new ones.","Prefer approved Models over raw Sources for business answers.","Choose explore for inspection, build for authoring, and operate only when the task requires connections, runs, automations, Tracking, or Prospecting effects.","When the task needs only part of a mode, send requestedScopes as an exact subset of that mode; workspace:read remains required.","Read /v1/session before acting. Its scopes, modelAccessMode, allowedModelKeys, and agentApiPermissions are the effective grant.","The capabilities returned by GET /v1 describe only routes currently mounted under /v1. The same bearer can use linked compatibility reads under /api/agent and /api/data when agentApiPermissions allows them.","Use direct v1 domain writes only when the current task and delegated scopes authorize the effect.","Do not start a delegated Quest Chat unless the session separately grants chat.run.","Return ids, receipts, and links for every artifact, Chat, or run you create.","Never print, paste into a prompt, or commit an issued bearer token; write it directly to protected credential storage."],"quickstart":["1. GET /v1 and this guide to inspect the live API and choose explore, build, or operate based on the task.","2. POST /v1/auth/device with a connectionName, purpose, the chosen access mode, and requestedScopes when an exact subset is sufficient.","3. Open verificationUrlComplete for the person and ask them to compare the displayed userCode before approval.","4. Poll POST /v1/auth/token no faster than pollAfterSeconds and write the one-time token response directly to protected credential storage.","5. GET /v1/session, inspect its Model policy and agentApiPermissions, then use the linked route that produces the first useful result."],"_links":{"self":{"href":"https://app.proformalabs.ai/api/agent","method":"GET","authenticated":false},"human_login":{"href":"https://app.proformalabs.ai/login","method":"GET","authenticated":false},"human_authorization":{"href":"https://app.proformalabs.ai/connect/agent","method":"GET","authenticated":true},"v1":{"href":"https://app.proformalabs.ai/v1","method":"GET","authenticated":false},"device_authorization":{"href":"https://app.proformalabs.ai/v1/auth/device","method":"POST","authenticated":false},"token_exchange":{"href":"https://app.proformalabs.ai/v1/auth/token","method":"POST","authenticated":false},"session":{"href":"https://app.proformalabs.ai/v1/session","method":"GET","scope":"token"},"filesystem":{"href":"https://app.proformalabs.ai/v1/fs{?path,depth,download,revision}","method":"GET|PUT","templated":true,"scope":"workspace:read|workspace:write"},"page_validation":{"href":"https://app.proformalabs.ai/v1/pages/validate","method":"POST","scope":"workspace:read"},"connection_settings":{"href":"https://app.proformalabs.ai/settings/agents","method":"GET","authenticated":true},"whoami":{"href":"https://app.proformalabs.ai/api/agent/whoami","method":"GET","scope":"token"},"context":{"href":"https://app.proformalabs.ai/api/agent/context","method":"POST","scope":"context:read"},"catalog":{"href":"https://app.proformalabs.ai/api/agent/catalog{?q,type}","method":"GET","templated":true,"scope":"catalog:read"},"models":{"href":"https://app.proformalabs.ai/api/agent/models{/:key}","method":"GET","templated":true,"scope":"catalog:read"},"sources":{"href":"https://app.proformalabs.ai/api/agent/sources{/:key}","method":"GET","templated":true,"scope":"catalog:read"},"pages":{"href":"https://app.proformalabs.ai/api/agent/pages{/:idOrSlug}","method":"GET","templated":true,"scope":"context:read"},"actions":{"href":"https://app.proformalabs.ai/api/agent/actions{/:idOrName}","method":"GET","templated":true,"scope":"context:read"},"data":{"href":"https://app.proformalabs.ai/api/data/models/{modelKey}/query","method":"POST","templated":true,"scope":"data:api"},"connections":{"href":"https://app.proformalabs.ai/api/agent/connections{/:provider/:action}","method":"GET|POST","templated":true,"scope":"connections:read|connections:manage"},"databases":{"href":"https://app.proformalabs.ai/api/agent/databases{/:idOrSlug}","method":"GET|POST","templated":true,"scope":"context:read|data:define"},"prospecting":{"href":"https://app.proformalabs.ai/api/agent/prospecting/{resource}","method":"GET|POST","templated":true,"scope":"prospecting:read|prospecting:write|prospecting:reveal","sourceExportScope":"prospecting:write+data:define"},"tracking":{"href":"https://app.proformalabs.ai/api/agent/tracking/{resource}","method":"GET|POST|PATCH|DELETE","templated":true,"scope":"tracking:read|tracking:key:create|tracking:write"},"runs":{"href":"https://app.proformalabs.ai/api/agent/actions/{actionIdOrName}/executions{/:executionId}","method":"GET|POST","templated":true,"scope":"runs:read|runs:operate"},"start_run":{"href":"https://app.proformalabs.ai/api/agent/actions/{actionIdOrName}/run","method":"POST","templated":true,"scope":"runs:operate"},"automations":{"href":"https://app.proformalabs.ai/api/agent/actions/{actionIdOrName}/triggers{/:triggerId}","method":"GET|POST|PATCH|DELETE","templated":true,"scope":"context:read|automations:manage"},"automation_dispatches":{"href":"https://app.proformalabs.ai/api/agent/automation-dispatches{?status,bindingId,limit}","method":"GET","templated":true,"scope":"runs:read"},"retry_automation_dispatch":{"href":"https://app.proformalabs.ai/api/agent/automation-dispatches/{dispatchId}/retry","method":"POST","templated":true,"scope":"runs:operate"},"test_automation_event":{"href":"https://app.proformalabs.ai/api/agent/actions/{actionIdOrName}/triggers/{triggerId}/test-event","method":"POST","templated":true,"scope":"runs:operate"},"delegated_chat_runs":{"href":"https://app.proformalabs.ai/api/agent-api/chat-runs{/:runId}","method":"GET|POST","templated":true,"scope":"chat:run"},"mcp":{"href":"https://app.proformalabs.ai/mcp","method":"POST","scope":"varies by tool"},"analysis_mcp":{"href":"https://app.proformalabs.ai/mcp/analysis","method":"POST","scope":"chat:run"},"llms":{"href":"https://proformalabs.ai/llms.txt","method":"GET"},"agent_guide":{"href":"https://proformalabs.ai/llms-full.txt","method":"GET"},"cli_guide":{"href":"https://proformalabs.ai/cli","method":"GET"},"mcp_guide":{"href":"https://proformalabs.ai/mcp","method":"GET"}}}