> ## Documentation Index > Fetch the complete documentation index at: https://developers.askparable.com/llms.txt > Use this file to discover all available pages before exploring further. # Read a Plot's data > Returns a page of rows from a saved Plot, under the Policies in force. The server works out where the data comes from and returns it alongside the definition it was read with. ## Access An MCP token or a Parable token can call this operation. See [Authentication](/getting-started/authentication.md) for the kinds of token. Your roles must grant one of `tenant.parables.view`, `tenant.parables.manage`. ## Errors * `PA-AU-040`: The Plot data command or parameters are not conforming. Select one valid Plot and provide parameters that match its contract. * `PA-AU-003`: The Plot context or contract changed during the read. Refresh Plot context and retry with the latest revision. * `PA-AU-001`: The Parable, Plot, or Report data was not found. Check the rootRefId and selected Plot or Report. * `PA-AU-019`: The command sent sql of its own, and the caller could not save that SQL as this Plot. Saving it takes tenant.parables.manage, Publishing or Primary on the Parable, and edit.plots or create.plots from the Plot's Pane Policies. Read the Plot without sql to get its saved rows. Running other SQL needs the right to save that Plot. * `QL-TO-002`: The Plot query ran past its time budget and was stopped (HTTP 504). The message names the budget. Narrow the Plot with a filter, a shorter date range or an aggregation, then read it again. * `QL-IN-008`: Too many queries were running, so the read did not start (HTTP 429). Read the Plot again after a short pause. * `QL-SQ-010`: The Plot read would send more paid AI calls (ponder, embed and the Jev functions) than one query may send, so it stopped before the next call (HTTP 400). The message names the limit and the function. Call the AI function over fewer rows, or read a stored Refresh of the Plot. * `QL-SQ-011`: The Plot read's paid AI calls would cost more than one query may spend, so it stopped before the next call (HTTP 400). The message names the limit and what the read spent. Call the AI function over fewer rows or with a cheaper model, or read a stored Refresh of the Plot. * `QL-TN-007`: The read asked for a stored Refresh, and Provider Policies or source permissions narrow what the caller reads of a Provider table behind it. The Refresh holds rows the caller cannot read, so it is refused (HTTP 403). Do not read this Refresh again as this caller. Someone whom no Provider Policy or source permissions narrow on those tables can open it. ## OpenAPI ````yaml /api-reference/openapi.json post /api/parable/authoring/primaries/{rootRefId}/plots/data openapi: 3.0.3 info: description: >- Use the Workspace API to work with artifacts, connectors, Parables, and account resources. title: Workspace API version: v2026.10.22.1 servers: [] security: [] paths: /api/parable/authoring/primaries/{rootRefId}/plots/data: post: tags: - Parable authoring summary: Read a Plot's data description: >- Returns a page of rows from a saved Plot, under the Policies in force. The server works out where the data comes from and returns it alongside the definition it was read with. operationId: ParableAuthoringReadParablePlotDataHandler parameters: - description: >- Workspace slug. Overrides subdomain-based workspace resolution when provided. in: header name: X-Tenant required: false schema: example: acme type: string - description: Optional request correlation ID echoed back in the response. in: header name: X-Request-ID required: false schema: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string - description: rootRefId parameter in: path name: rootRefId required: true schema: description: UUID v4 with automatic base62 encoding for client-facing APIs type: string - in: query name: refId required: false schema: description: UUID v4 with automatic base62 encoding for client-facing APIs type: string - in: query name: versionId required: false schema: description: UUID v4 with automatic base62 encoding for client-facing APIs type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PlotDataCommand' required: true responses: '200': content: application/json: schema: properties: data: $ref: '#/components/schemas/PlotDataResponse' links: $ref: '#/components/schemas/ResponseLinks' meta: $ref: '#/components/schemas/ResponseMeta' required: - data - meta type: object description: Successful response headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '400': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: >- The request is not valid. `detail` says why. A value that breaks a field rule gives the code `WA-VL-001` and an `errors` member that names each field. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '401': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: The token is missing, malformed, revoked, or expired. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '403': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: >- The token cannot make this request. For example, the roles of its owner do not allow the operation. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '404': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: The resource that the path names was not found. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '500': content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' description: The request failed on the server. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' security: - bearerAuth: [] x-codeSamples: - label: TypeScript SDK lang: typescript source: >- import { WebApiSDK } from "@parable-platform/web-api-sdk"; import type { PlotDataCommand } from "@parable-platform/web-api-types"; const sdk = new WebApiSDK({ baseUrl: process.env.PARABLE_API_URL!, auth: { token: process.env.PARABLE_API_TOKEN! }, requestInterceptor: (config) => ({ ...config, headers: { ...config.headers, "X-Tenant": process.env.PARABLE_WORKSPACE! }, }), }); const input: PlotDataCommand = JSON.parse(`{ "reading": { "kind": "CURRENT" }, "pageSize": 1 }`); const query = {}; const result = await sdk.parableAuthoring.readParablePlotData( "example", input, query ); - label: Python SDK lang: python source: >- import json import os from parable_types_web_api import PlotDataCommand from parable_web_api_sdk import ClientConfig, WebApiSDK sdk = WebApiSDK( ClientConfig( base_url=os.environ["PARABLE_API_URL"], auth_token=os.environ["PARABLE_API_TOKEN"], default_headers={"X-Tenant": os.environ["PARABLE_WORKSPACE"]}, ) ) input_data = PlotDataCommand.model_validate( json.loads("{\"reading\":{\"kind\":\"CURRENT\"},\"pageSize\":1}"), ) result = sdk.parable_authoring.read_parable_plot_data('example', input_data, ref_id=None, version_id=None) - label: Rust SDK lang: rust source: >- use parable_web_api_sdk::{namespaces, types, ClientConfig, RequestOptions, WebApiSdk}; let sdk = WebApiSdk::new(ClientConfig::with_base_url( std::env::var("PARABLE_API_URL")?, Some(std::env::var("PARABLE_API_TOKEN")?), None, ))?; let options = RequestOptions::with_header("X-Tenant", std::env::var("PARABLE_WORKSPACE")?, None, None); let input: types::PlotDataCommand = serde_json::from_value( serde_json::json!({ "reading": { "kind": "CURRENT" }, "pageSize": 1 }), )?; let query = namespaces::parable_authoring::ReadParablePlotDataQueryParams { ref_id: None, version_id: None, }; let result = sdk.parable_authoring.read_parable_plot_data( serde_json::from_value(serde_json::json!("example"))?, input, Some(&query), Some(&options) ).await?; - label: Go SDK lang: go source: "sdk, err := webapisdk.New(webapisdk.SDKConfig{\n\tBaseURL: os.Getenv(\"PARABLE_API_URL\"),\n\tAuth: &webapisdk.AuthConfig{Token: os.Getenv(\"PARABLE_API_TOKEN\")},\n\tRequestInterceptor: func(ctx context.Context, req *http.Request) error {\n\t\treq.Header.Set(\"X-Tenant\", os.Getenv(\"PARABLE_WORKSPACE\"))\n\t\treturn nil\n\t},\n})\nif err != nil {\n\treturn err\n}\n\nvar input webapitypes.PlotDataCommand\nif err := json.Unmarshal([]byte(`{\"reading\":{\"kind\":\"CURRENT\"},\"pageSize\":1}`), &input); err != nil {\n\treturn err\n}\nquery := &namespaces.ParableAuthoringReadParablePlotDataQueryParams{}\nresult, err := sdk.ParableAuthoringNamespace.ReadParablePlotData(ctx, \"example\", input, query)" components: schemas: PlotDataCommand: description: >- A request for a page of a Plot's data. It names the Plot, never a schema, table or storage location: Parable resolves the target. properties: columns: description: Optional projected columns; null means all schema columns. items: type: string nullable: true type: array cursor: description: >- Opaque pagination cursor minted by the server; null starts at the first page. Its encoding is private and can change. Send it back unchanged. nullable: true type: string expectedContractHash: description: >- Contract captured by the renderer; stale declarations refuse before execution. maxLength: 64 minLength: 64 nullable: true pattern: ^[0-9a-f]{64}$ type: string expectedPieceVersions: description: >- The read fence: the versions of the Pieces that this read reads, as the reader's view holds them (PlotDataMeta.pieceVersions of the read before, updated by Piece deltas). The read is refused with PA-AU-077 only when one of them changed, never because another Piece of the set of Changes changed. When present, it replaces the fence on expectedRefRevision. items: $ref: '#/components/schemas/PlotReadPieceVersion' maxItems: 256 nullable: true type: array expectedRefRevision: description: >- Draft revision captured by the React host; prevents silent definition drift. format: int64 maximum: 9007199254740991 minimum: 1 nullable: true type: integer pageSize: description: Page size, from 1 to 10,000 rows. format: int64 maximum: 10000 minimum: 1 type: integer paneValues: description: |- The reader's on-screen values of the Panes the Plot reads by name. A Pane left out reads its saved value: Me, then This Parable, then the Plot's default. At most 1 MB in all. items: $ref: '#/components/schemas/PlotReadPaneValue' nullable: true type: array parameters: description: Omitted uses saved bindings; a supplied array replaces all bindings. items: description: 'Any valid JSON value: object, array, primitive, or null' nullable: true type: array plot: description: Plot slug within the Parable (immutable SQL segment). maxLength: 255 minLength: 1 nullable: true pattern: ^[a-z0-9]+(?:[-_][a-z0-9]+)*$ type: string plotKey: description: Stable declared Plot identity; alternative to the catalog slug. nullable: true pattern: >- ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ type: string reading: $ref: '#/components/schemas/PlotDataReading' requireMaterialized: description: >- Read a compatible completed artifact only; never execute ordinary SQL. nullable: true type: boolean sort: description: Ordered sort terms; null means server default order. items: $ref: '#/components/schemas/PlotDataSortTerm' nullable: true type: array sql: description: >- Constructed SQL for the selected declared contract, run in place of the saved source. Accepted only from someone who could save it as this Plot: tenant.parables.manage, Publishing or Primary on the Parable, and edit.plots or create.plots from the Plot's Pane Policies. minLength: 1 nullable: true pattern: ^[\s\S]*$ type: string required: - reading - pageSize type: object PlotDataResponse: description: |- Workspace-facing Plot data page. No storage-engine fields on this shape. properties: columns: items: $ref: '#/components/schemas/PlotDataColumn' type: array findings: description: >- What Prepare would record for this Plot with the previewed SQL. Filled only when the command carries SQL to preview on a draft ref; null otherwise. Empty means Prepare would record nothing. items: $ref: '#/components/schemas/PlotPrepareFinding' nullable: true type: array meta: $ref: '#/components/schemas/PlotDataMeta' nextCursor: nullable: true type: string rows: items: $ref: '#/components/schemas/PlotDataRow' type: array required: - columns - rows - meta type: object ResponseLinks: properties: first: nullable: true type: string last: nullable: true type: string next: nullable: true type: string prev: nullable: true type: string type: object ResponseMeta: properties: requestId: description: Unique identifier for the request type: string totalCount: description: Total count of items for paginated responses nullable: true type: integer required: - requestId type: object ProblemDetails: description: An error response in the Problem Details format (RFC 9457). properties: code: description: The stable error code, when the problem has one. example: WA-VL-001 type: string detail: description: What went wrong with this request. type: string details: description: >- Structured facts about the refusal, such as the entity or the path it concerns. Only some refusals have it. errors: description: >- The fields or filters that failed validation. Only a validation or filter error has it. requestId: description: >- The ID of the request, when the problem has one. The `X-Request-ID` response header always has it. type: string status: description: The HTTP status code. example: 400 type: integer title: description: A short summary, usually the text of the HTTP status. example: Bad Request type: string type: description: >- The problem type. It is `about:blank`: the status and `code` identify the problem. example: about:blank type: string required: - type - title - status - detail type: object PlotReadPieceVersion: description: |- One Piece version that a read used or expects: the Plot, a Plot it reads at any depth, or a Pane whose relation it binds. properties: pieceKey: description: UUID v4 with automatic base62 encoding for client-facing APIs pattern: >- ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ type: string version: description: >- Signed 64-bit integer; range bounded by JavaScript's safe-integer ceiling. format: int64 maximum: 9007199254740991 minimum: -9007199254740991 type: integer required: - pieceKey - version type: object PlotReadPaneValue: description: >- A Pane's value as the reader sees it on screen, unsaved, sent with a Plot read so the Plot reads the reader's current filters. Parable checks it against the Pane's `preferences`. properties: paneKey: description: UUID v4 with automatic base62 encoding for client-facing APIs pattern: >- ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ type: string value: description: 'Any valid JSON value: object, array, primitive, or null' required: - paneKey - value type: object PlotDataReading: description: >- Requested data reading, shared by React context and the Plot data protocol. REPORT_RUN requires reportRunId; CURRENT requires null. Boundary validation enforces this cross-field invariant in every executor. properties: kind: $ref: '#/components/schemas/PlotDataReadingKind' reportRunId: description: UUID v4 with automatic base62 encoding for client-facing APIs nullable: true pattern: >- ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ type: string required: - kind type: object PlotDataSortTerm: properties: column: type: string dir: $ref: '#/components/schemas/PlotDataSortDirection' required: - column - dir type: object PlotDataColumn: description: One ordered response column. properties: name: type: string primitive: description: >- Scalar primitive kind from scalar-lib metadata (e.g. String, Int), validated by the scalar. maxLength: 16 minLength: 3 pattern: ^(String|Int|Float|Bool|Type)$ type: string scalarRef: description: >- Canonical name of a Parable scalar (e.g., Identity.UUID, Generic.Int64) maxLength: 128 minLength: 3 nullable: true pattern: ^[A-Z][A-Za-z0-9]*\.[A-Z][A-Za-z0-9]*$ type: string required: - name - primitive type: object PlotPrepareFinding: description: >- One finding Prepare would record for a Plot, as Preview returns it (spec 0084, Surfaces). Preview runs Prepare's own evaluation for the Plot it runs, so the code and message are the ones Prepare writes; every one blocks Prepare. properties: code: $ref: '#/components/schemas/ParablePrepareFindingCodeEnum' message: type: string required: - code - message type: object PlotDataMeta: description: >- Resolved result metadata. Field names align with parable-reporting views: publishedCommitId, occurredAt, plotEntityVersion. properties: boundPaneKeys: description: >- The Panes whose relations this read bound, after views expand. A Preference delta of one of these Panes runs the read again. Null when the platform cannot tell which Panes the read reads: then every delta runs it again. items: description: UUID v4 with automatic base62 encoding for client-facing APIs pattern: >- ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ type: string nullable: true type: array consumerContractHash: description: >- Selected consumer contract that admitted these captured or current values. maxLength: 64 minLength: 64 nullable: true pattern: ^[0-9a-f]{64}$ type: string context: description: Trusted execution snapshot captured before reading data. oneOf: - $ref: '#/components/schemas/ParableContext' - enum: - null nullable: true type: object contractHash: description: Contract and source that actually produced this response. maxLength: 64 minLength: 64 nullable: true pattern: ^[0-9a-f]{64}$ type: string currentDirectoryData: description: >- A directory could not be read as of the selected Refresh. Its current rows are returned and the platform displays that distinction beside the Pane. nullable: true type: boolean freshness: description: >- ISO8601 datetime string. Epoch wire values keep this scalar and declare x-temporal-format (unix, unix_millis, unix_micros, unix_nanos) on the property; the unit is never guessed from digit count. format: date-time type: string inputHydration: description: >- Native representation metadata; excludes private validator literals and source. nullable: true materialized: description: >- True only when these rows were read from the selected completed artifact. type: boolean occurredAt: description: Run occurredAt for REPORT_RUN; null for CURRENT. format: date-time nullable: true type: string outputHydration: description: 'Any valid JSON value: object, array, primitive, or null' nullable: true parableReads: description: >- The Platform Parables this read read through Plots of other Parables, each with the Release and Refresh read. Null or empty when it read none. items: $ref: '#/components/schemas/PlotDataParableRead' nullable: true type: array pieceVersions: description: >- The versions of the Pieces this read read: the Plot, its upstream Plots and the Panes it bound. The next read of the same Plot sends them as PlotDataCommand.expectedPieceVersions. items: $ref: '#/components/schemas/PlotReadPieceVersion' nullable: true type: array plotEntityVersion: description: Sealed Plot version for REPORT_RUN; null for CURRENT. format: int64 maximum: 9007199254740991 minimum: -9007199254740991 nullable: true type: integer plotKey: description: Stable logical Plot identity across definition versions. nullable: true pattern: >- ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ type: string publishedCommitId: description: >- Published commit the read resolved to, the same as ParableReportRunView.publishedCommitId, and never a version string. Null only for CURRENT against a draft proposal ref (design mode), which has no published commit. REPORT_RUN always fills it. nullable: true pattern: >- ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ type: string reading: $ref: '#/components/schemas/PlotDataReading' description: Resolved reading (reportRunId filled for REPORT_RUN). sample: oneOf: - $ref: '#/components/schemas/PlotDataSampleMeta' - enum: - null nullable: true type: object sampled: description: |- Kept as an explicit wire flag per the spec. The server guarantees sampled == (sample != null); schema cannot couple the two fields. type: boolean settingsChanged: description: >- True when a Preference row of a Pane that this stored output's Plot reads changed after the Refresh that made the output started. The Pane then says "These settings changed since the last run" and offers Preview and Run. Parable fills it on a read of a stored output. Null on a live read. nullable: true type: boolean sourceHash: description: Lowercase hexadecimal SHA-256 digest maxLength: 64 minLength: 64 nullable: true pattern: ^[0-9a-f]{64}$ type: string sourceImplementationId: description: >- Producer implementation row and version; a Report may have been produced by an older definition. nullable: true pattern: >- ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ type: string sourceImplementationVersion: description: >- Signed 64-bit integer; range bounded by JavaScript's safe-integer ceiling. format: int64 maximum: 9007199254740991 minimum: -9007199254740991 nullable: true type: integer tableCardinality: description: >- Signed 64-bit integer; range bounded by JavaScript's safe-integer ceiling. format: int64 maximum: 9007199254740991 minimum: -9007199254740991 nullable: true type: integer upstreamPlotKeys: description: The Plots this read reads, at every depth. Null when unknown. items: description: UUID v4 with automatic base62 encoding for client-facing APIs pattern: >- ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ type: string nullable: true type: array watermark: description: >- ISO8601 datetime string. Epoch wire values keep this scalar and declare x-temporal-format (unix, unix_millis, unix_micros, unix_nanos) on the property; the unit is never guessed from digit count. format: date-time nullable: true type: string required: - materialized - reading - sampled - freshness type: object PlotDataRow: description: 'One response row (named type: schema rejects nested array-of-array).' properties: cells: description: Cells in scalar-lib canonical JSON encoding, column order. items: description: 'Any valid JSON value: object, array, primitive, or null' type: array required: - cells type: object PlotDataReadingKind: description: A live reading or one concrete Report run. Draft previews use CURRENT. enum: - CURRENT - REPORT_RUN type: string PlotDataSortDirection: enum: - asc - desc type: string ParablePrepareFindingCodeEnum: enum: - conflict - stale_base - source_retracted - plot_schema_missing - plot_diagnostics_stale - plot_diagnostic_blocking - plot_plan_failed - missing_preview - type_not_grown - preference_conversion - ref_missing - ref_orphaned_rows - policy_setting_read - policy_lockout type: string ParableContext: description: |- Public, host-owned execution coordinates shared by React and SQL. Requested coordinates do not attest to returned data provenance or grant access. The host resolves authority and authorizes every sensitive call. properties: actor: description: >- Initiating actor, if any. Null never means an unrestricted execution. oneOf: - $ref: '#/components/schemas/ParableContextActor' - enum: - null nullable: true type: object data: $ref: '#/components/schemas/PlotDataReading' mode: $ref: '#/components/schemas/ParableContextMode' parable: $ref: '#/components/schemas/ParableContextDefinition' permissions: description: >- Reserved empty list in every runtime. Use raci and Pane Policies for Parable presentation; host permission grants are enforced outside context. items: description: Hierarchical permission string (e.g., 'admin.users.read') maxLength: 255 pattern: ^[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*)*$ type: string type: array principal: $ref: '#/components/schemas/ParableContextActor' description: >- Identity whose authority runs this operation; required even on scheduled work. raci: $ref: '#/components/schemas/ParableRaciRoleEnum' viewAs: description: |- The person previewing this Parable as the principal (View as); null otherwise. The server refuses every write while a preview runs (PA-AU-044), so a Pane shows read-only controls when it is set. oneOf: - $ref: '#/components/schemas/ParableContextActor' - enum: - null nullable: true type: object workspace: $ref: '#/components/schemas/ParableContextWorkspace' required: - workspace - parable - data - principal - permissions - raci - mode type: object PlotDataParableRead: description: One Platform Parable a read read through another Parable's Plots. properties: empty: description: >- True when its Plots read as empty tables: it is not Visible in the Workspace, or it completed no Refresh by the AS OF time of the reading Parable's Refresh. type: boolean parableId: description: UUID v4 with automatic base62 encoding for client-facing APIs pattern: >- ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ type: string releaseId: description: >- The Platform Parable's Release that made the rows read: for a view, the Release the read reads; for a stored Plot, the Release whose Refresh made the output. A stored Plot is read by its columns, so that can be another Release with the same columns, and one Parable can be listed once for each Release. pattern: >- ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ type: string reportRunId: description: >- The Refresh of it whose stored output was read. Null when the read read none of its stored Plots, or read them empty. nullable: true pattern: >- ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ type: string required: - parableId - releaseId - empty type: object PlotDataSampleMeta: description: >- Sample accounting when the read was forced-sampled (design-mode Current). properties: candidateCount: description: >- Signed 64-bit integer; range bounded by JavaScript's safe-integer ceiling. format: int64 maximum: 9007199254740991 minimum: -9007199254740991 type: integer measuredCost: description: Monetary amount in smallest currency unit (e.g., cents for USD) format: int64 maximum: 9007199254740991 minimum: 0 type: integer projectedFullRunCost: description: Monetary amount in smallest currency unit (e.g., cents for USD) format: int64 maximum: 9007199254740991 minimum: 0 nullable: true type: integer size: description: >- Signed 64-bit integer; range bounded by JavaScript's safe-integer ceiling. format: int64 maximum: 9007199254740991 minimum: -9007199254740991 type: integer required: - size - candidateCount - measuredCost type: object ParableContextActor: description: >- An identity resolved by the host; it contains no credential or session secret. properties: actorId: description: UUID v4 with automatic base62 encoding for client-facing APIs pattern: >- ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ type: string actorKind: $ref: '#/components/schemas/ParableActorKindEnum' email: description: >- Authenticated account email resolved by the server, never a caller parameter or inferred identity match. format: email maxLength: 255 nullable: true pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$ type: string required: - actorId - actorKind type: object ParableContextMode: description: Presentation mode; this never grants a permission. enum: - personal - published type: string ParableContextDefinition: properties: handle: description: >- A mutable camelCase code, path, and file identifier; URLs use stable UUIDs maxLength: 200 minLength: 1 pattern: ^[a-z][A-Za-z0-9]*$ type: string parableId: description: UUID v4 with automatic base62 encoding for client-facing APIs pattern: >- ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ type: string revision: $ref: '#/components/schemas/ParableContextRevision' required: - parableId - handle - revision type: object ParableRaciRoleEnum: enum: - responsible - accountable - consulted - informed type: string ParableContextWorkspace: description: The Workspace a Parable runs in. Every Parable runs in a Workspace. properties: workspaceId: description: UUID v4 with automatic base62 encoding for client-facing APIs pattern: >- ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ type: string required: - workspaceId type: object ParableActorKindEnum: description: >- The kind of actor a Parable responsibility names: a person, an agent, or an organization. A Parable Platform, a Parable Workspace and a Role are organizations. enum: - organization - person - agent - platform - workspace - role type: string ParableContextRevision: description: >- Definition identity, never the version that happened to produce a Report. REF requires refId and refRevision with commitId null; COMMIT requires commitId with both ref fields null. Executors validate these invariants. properties: commitId: description: UUID v4 with automatic base62 encoding for client-facing APIs nullable: true pattern: >- ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ type: string kind: $ref: '#/components/schemas/ParableContextRevisionKind' refId: description: UUID v4 with automatic base62 encoding for client-facing APIs nullable: true pattern: >- ^([0-9A-Za-z]{1,22}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ type: string refRevision: description: >- Signed 64-bit integer; range bounded by JavaScript's safe-integer ceiling. format: int64 maximum: 9007199254740991 minimum: -9007199254740991 nullable: true type: integer required: - kind type: object ParableContextRevisionKind: description: >- The definition being executed, independently of its selected data reading. enum: - ref - commit type: string headers: X-Request-ID: description: >- The ID of the request. It is the `X-Request-ID` value that you sent, or an ID that the server made. Give it when you report a problem. schema: type: string securitySchemes: bearerAuth: description: >- A personal access token, which starts with `pat_`. A Parable token can call each operation that the roles of its owner allow. An MCP token can call only the read operations that are open to agents. A SQL token does not work on this API. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.