# Permute Developer Documentation

> Build trusted business-data integrations with the Permute TypeScript SDK, MCP server, and public REST API.

Permute is an enterprise financial intelligence layer. It connects operational, customer, financial, and risk data into a governed model that powers reporting, analytics, AI, and programmatic products. Its public interfaces provide source discovery, interpreted answers, evidence search, file and custom dataset ingestion, and read-only structured queries.

## Interface Selection

- Prefer the `@permute/sdk` TypeScript SDK for the happy path of a programmatic integration. It provides typed requests and responses and handles multi-step workflows such as uploads and answer-job polling.
- Prefer the Permute MCP server for end-user convenience when a person wants to explore or ask questions of trusted workspace data from an MCP-compatible AI client.
- Use the REST API as the raw HTTP interface for custom clients, unsupported runtimes, or low-level transport control.
- The SDK, MCP server, and REST API share the same curated contract and underlying permission system. REST and SDK requests use API keys. Hosted MCP connectors use OAuth and the connecting user's permissions.
- Workspace and dataset mutations are SDK or REST operations unless a capability is explicitly documented as an MCP tool.

## Agent Instructions

- Treat workspace, source, dataset, and job IDs as opaque identifiers returned by Permute. Never invent IDs.
- Discover sources before answering questions or writing SQL. Inspect a source before selecting exact table or field names.
- Prefer answer jobs for interpreted business questions, evidence search for ranked supporting material, and structured queries only for exact read-only rows.
- Preserve citations, confidence, and source attribution when presenting Permute results.
- Never expose API keys in browser code, generated output, logs, or conversation text.

## Get Started

- [Documentation overview](https://permute.ai/docs): Choose between the SDK, MCP server, and REST API.
- [SDK quickstart](https://permute.ai/docs/quickstart): Install the TypeScript SDK and make the first workspace-scoped request.
- [@permute/sdk on npm](https://www.npmjs.com/package/@permute/sdk): Public TypeScript SDK package.
- [Authentication](https://permute.ai/docs/authentication): Create API keys, select a workspace, and understand access grants.
- [MCP connectors](https://permute.ai/docs/mcp): Publish selected workspace sources and connect them to Claude with OAuth.

## Integration Guides

- [Set up a workspace](https://permute.ai/docs/guides/workspace): Create a workspace with an organization-scoped management key, then use its ID for workspace data operations.
- [Ask a business question](https://permute.ai/docs/guides/analysis): Discover an accessible source and ask Permute a business question. The SDK waits for the durable analysis automatically.
- [Upload and process a file](https://permute.ai/docs/guides/file-upload): Create a file dataset, PUT the bytes to its signed S3 target, and poll while processing runs automatically. CSV, TSV, JSON, NDJSON, and Parquet files can be up to 1 GiB; other supported file types can be up to 100 MiB. Permute applies the limit from contentType.
- [Sync related application data](https://permute.ai/docs/guides/custom-dataset): Create or recover one stable custom dataset. Replace current source state when rows can change or disappear; append only for additive sources.
- [Build and publish a data flow](https://permute.ai/docs/guides/data-flow): Turn two sample orders into a published revenue total of 350. This complete SDK example creates the input, saves a transform, runs the flow, checks its output, and publishes it (no built-in coding agent required).
- [Restore and publish an operation](https://permute.ai/docs/guides/versioning): Recover an earlier revenue calculation, test its output, and publish the restored draft. Restore preserves history (including the later revision) and does not start a run.
- [Manage context with facts and skills](https://permute.ai/docs/guides/context): Save business definitions as organization facts and reusable instructions as shared Markdown skills. Create, read, replace, and delete sample context through the SDK.
- [Find supporting evidence](https://permute.ai/docs/guides/search): Retrieve the most relevant evidence and citations for a specific claim or topic. Search reranks results by default.
- [Retrieve exact rows](https://permute.ai/docs/guides/query): Inspect the source, then run read-only SQL against its exact table names when you need rows instead of interpretation.

## Connector Guides

- [Shopify connector](https://permute.ai/docs/connectors/shopify): Create a merchant-owned Dev Dashboard app, grant access scopes, install it, and connect it to Permute.
- [Autodesk Forma connector](https://permute.ai/docs/connectors/autodesk): Add Permute to a Forma hub, authorize an Autodesk user, and sync accessible project, document, company, and Cost Management data.
- [Amazon S3 connector](https://permute.ai/docs/connectors/s3): Assume a customer-owned read-only IAM role and materialize mapped CSV, TSV, pipe-separated, semicolon-separated, JSON, NDJSON, or Parquet objects.

## API Reference

- [API reference overview](https://permute.ai/docs/api-reference): Browse the complete contract-derived REST surface.
- [GET /v1/workspaces](https://permute.ai/docs/api-reference/workspaces-list): List workspaces. Discover the workspaces this API key can read.
- [POST /v1/workspaces](https://permute.ai/docs/api-reference/workspaces-create): Create a workspace. Provision a new workspace before uploading or querying its data.
- [GET /v1/workspaces/{workspaceId}](https://permute.ai/docs/api-reference/workspaces-get): Get a workspace. Read the current name, context, and visibility of one workspace.
- [PATCH /v1/workspaces/{workspaceId}](https://permute.ai/docs/api-reference/workspaces-update): Update a workspace. Change a workspace name or business context.
- [DELETE /v1/workspaces/{workspaceId}](https://permute.ai/docs/api-reference/workspaces-delete): Delete a workspace. Remove a workspace that should no longer be available.
- [GET /v1/sources](https://permute.ai/docs/api-reference/sources-list): List queryable sources. Start here to discover queryable datasets and connectors in the current workspace.
- [GET /v1/sources/{sourceId}](https://permute.ai/docs/api-reference/sources-get): Get a source. Inspect tables and fields before asking for exact rows or writing SQL.
- [GET /v1/dashboards/{dashboardId}/source](https://permute.ai/docs/api-reference/dashboards-source-get): Get dashboard source. Read an existing dashboard source before editing its TSX.
- [PUT /v1/dashboards/{dashboardId}/source](https://permute.ai/docs/api-reference/dashboards-source-update): Update dashboard source. Replace a dashboard frontend after reading and editing its complete TSX source.
- [POST /v1/datasets](https://permute.ai/docs/api-reference/datasets-create): Create a dataset. Create or retrieve a keyed custom dataset, or create a file dataset with a signed upload target.
- [GET /v1/datasets](https://permute.ai/docs/api-reference/datasets-get-by-key): Get a dataset by key. Resolve the dataset associated with an exact caller-owned stable key.
- [GET /v1/datasets/{datasetId}](https://permute.ai/docs/api-reference/datasets-get): Get a dataset. Read the current configuration, version, status, and tables for a keyed dataset.
- [GET /v1/datasets/{datasetId}/download](https://permute.ai/docs/api-reference/datasets-download): Download a file dataset. Retrieve the original bytes uploaded for a file dataset.
- [DELETE /v1/datasets/{datasetId}](https://permute.ai/docs/api-reference/datasets-delete): Delete a dataset. Remove one file or custom dataset that should no longer be available.
- [POST /v1/datasets/{datasetId}/tables](https://permute.ai/docs/api-reference/datasets-write-tables): Write dataset tables. Write named JSON tables within an existing keyed dataset.
- [POST /v1/search](https://permute.ai/docs/api-reference/search-create): Search business evidence. Find evidence snippets, records, and text blocks when support for an answer matters.
- [POST /v1/answer-jobs](https://permute.ai/docs/api-reference/answer-jobs-create): Start an answer job. Start a durable Permute analysis when the answer may need multiple tool calls or larger source context.
- [GET /v1/answer-jobs/{answerJobId}](https://permute.ai/docs/api-reference/answer-jobs-get): Get an answer job. Poll a previously started analysis until it is completed or failed.
- [POST /v1/queries](https://permute.ai/docs/api-reference/queries-create): Run a structured query. Run read-only SQL when you already know the exact table names and source IDs.
- [GET /v1/operation-runs](https://permute.ai/docs/api-reference/operation-runs-list): List operation runs by workflow. Check progress after starting a data flow.
- [GET /v1/operations](https://permute.ai/docs/api-reference/operations-list): List operations. Discover operations, including drafts that have no published output.
- [GET /v1/operations/{operationId}](https://permute.ai/docs/api-reference/operations-get): Get an operation. Inspect an operation’s instructions, inputs, revisions, schedule, enablement, and next run time.
- [PATCH /v1/operations/{operationId}](https://permute.ai/docs/api-reference/operations-update): Schedule, pause, or resume an operation. Schedule a published operation or Data Flow, or pause and resume it.
- [GET /v1/operations/{operationId}/source](https://permute.ai/docs/api-reference/operations-source-get): Read operation code and inputs. Read handler code and current configured inputs before editing.
- [PUT /v1/operations/{operationId}/source](https://permute.ai/docs/api-reference/operations-source-update): Save operation code as a draft. Save a complete handler as a draft. First read getSource, edit that source, and pass its revision, dataFlowRevision, and updatedAt back as the expected values (the JSON values below are illustrative). A 409 conflict means the source or configuration changed; read again and reconcile your edits before retrying.
- [GET /v1/operations/{operationId}/runs](https://permute.ai/docs/api-reference/operations-runs-list): List the latest 50 operation runs. Track execution and inspect failures.
- [GET /v1/operations/{operationId}/runs/{runId}/output](https://permute.ai/docs/api-reference/operations-run-output): Inspect a completed run before publishing. Inspect exact completed run output before publishing.
- [POST /v1/operations/{operationId}/runs](https://permute.ai/docs/api-reference/operations-run): Run an operation or data flow. Test saved draft code or execute published code.
- [POST /v1/data-flows](https://permute.ai/docs/api-reference/data-flows-create): Create a draft data flow. Create a flow for an external agent to build.
- [GET /v1/data-flows/{dataFlowId}](https://permute.ai/docs/api-reference/data-flows-get): Get a data flow and its operation references. Read a flow’s operation references, edges, and revision.
- [POST /v1/data-flows/{dataFlowId}/commands](https://permute.ai/docs/api-reference/data-flows-command): Edit or publish a data flow. Add or edit operations, wire inputs, publish, or delete a flow.
- [GET /v1/facts](https://permute.ai/docs/api-reference/facts-list): List organization facts. Discover canonical business definitions and calculations.
- [GET /v1/facts/{factId}](https://permute.ai/docs/api-reference/facts-get): Get a fact. Read the exact rule referenced by a fact citation.
- [POST /v1/facts](https://permute.ai/docs/api-reference/facts-create): Create a fact. Define a shared business rule.
- [PUT /v1/facts/{factId}](https://permute.ai/docs/api-reference/facts-update): Replace a fact. Replace an existing business rule.
- [DELETE /v1/facts/{factId}](https://permute.ai/docs/api-reference/facts-delete): Delete a fact. Remove an obsolete organization rule.
- [GET /v1/skills](https://permute.ai/docs/api-reference/skills-list): List shared skills. Discover shared Markdown context before analysis.
- [GET /v1/skills/{path}](https://permute.ai/docs/api-reference/skills-get): Read a skill. Read a business instruction file.
- [PUT /v1/skills/{path}](https://permute.ai/docs/api-reference/skills-update): Create or replace a skill. Save reusable business context.
- [DELETE /v1/skills/{path}](https://permute.ai/docs/api-reference/skills-delete): Delete a skill. Remove obsolete business context.
- [GET /v1/organization/skills](https://permute.ai/docs/api-reference/organization-skills-list): List shared organization skills. Discover shared Markdown context before analysis.
- [GET /v1/organization/skills/{path}](https://permute.ai/docs/api-reference/organization-skills-get): Read an organization skill. Read a business instruction file.
- [PUT /v1/organization/skills/{path}](https://permute.ai/docs/api-reference/organization-skills-update): Create or replace an organization skill. Save reusable business context.
- [DELETE /v1/organization/skills/{path}](https://permute.ai/docs/api-reference/organization-skills-delete): Delete an organization skill. Remove obsolete business context.
- [GET /v1/resources/{resourceId}/revisions](https://permute.ai/docs/api-reference/resource-revisions-list): Read resource history and version state. Inspect history and get a version token before restoring or publishing.
- [GET /v1/resources/{resourceId}/revisions/{revisionId}](https://permute.ai/docs/api-reference/resource-revisions-get): Read a complete historical revision. Inspect the complete saved value before choosing a revision to restore.
- [POST /v1/resources/{resourceId}/revisions/{revisionId}/restore](https://permute.ai/docs/api-reference/resource-revisions-restore): Restore a revision as the current draft. Recover a previous definition without running or publishing it.
- [POST /v1/resources/{resourceId}/publish](https://permute.ai/docs/api-reference/resources-publish): Publish the current tested resource. Publish a successfully tested operation or Data Flow.

## Machine-Readable Resources

- [Complete documentation context](https://permute.ai/llms-full.txt): Full guides, interface rules, examples, and endpoint guidance in one Markdown document.
- [OpenAPI specification](https://api.permute.ai/openapi.json): OpenAPI 3 contract. The current endpoint requires a Permute API key.
- [Documentation sitemap](https://permute.ai/sitemap.xml): Crawlable index of public Permute pages.

## Optional

- [Permute website](https://permute.ai): Product, company, security, integration, and industry information.