> ## Documentation Index > Fetch the complete documentation index at: https://docs.narrative.io/llms.txt > Use this file to discover all available pages before exploring further. # Update a data plane > Update the display name and/or the description of a data plane owned by the authenticated company. Every field in the body is optional: a field that is omitted is left unchanged, and `description: null` clears the description. An empty body succeeds and changes nothing. Collaborators cannot update a data plane they do not own. ## OpenAPI ````yaml https://docs-cdn.narrative.io/api-reference/main/openapi.json patch /data-planes/{data_plane_id} openapi: 3.1.1 info: contact: email: support@narrative.io name: Narrative Support url: https://www.narrative.io termsOfService: https://www.narrative.io/legal/terms-of-service x-logo: url: >- https://cdn.narrative.io/images/company-logos/prod/narrative-logo-text-white.svg backgroundColor: rgb(9, 34, 166) altText: Narrative Logo description: >- The [Narrative Data Collaboration Platform](https://app.narrative.io) API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. The current version is a pre-release beta. It may result in unexpected behavior and there may be breaking changes in future releases up to the 1.0 release. title: Narrative Data Collaboration Platform API version: 2.4.x servers: - url: https://api-dev.narrative.io - url: https://api.narrative.io security: [] tags: - name: Access Rules description: >- Access rules let data providers control who can purchase their data and the terms of purchase. The `access-rules` API allows you to manage access rules for your datasets. Related guides: - [What is an access rule?](https://kb.narrative.io/access-rules) - name: Agent Conversations description: >- Build LLM-driven workflows that can call MCP tools, ask the caller for input, and return structured answers. A conversation pins a model, a system prompt, and a tool catalog. Each run sends the model a user message (or a batch of tool outputs from a previously-paused run); the model decides whether to answer directly, call a server-side tool (resolved by the platform via Model Context Protocol), or call a client-side tool (which pauses the run with `requires_action` and waits for the caller to reply). Related guides: - [Agent Conversations Reference](https://docs.narrative.io/reference/architecture/agent-conversations) - [Error catalog](https://docs.narrative.io/reference/architecture/agent-conversations/errors/conversation-not-found) - name: MCP Connections description: >- Connect external (non-Narrative) MCP servers so agent runs can call their tools with the calling user's own OAuth authorization. A connection is created interactively: `POST /mcp-connections` runs OAuth discovery and Dynamic Client Registration against the server and returns a consent URL; the user authorizes in a browser; the authorization server redirects to `GET /mcp-connections/callback`, which stores the authorization code and sends the browser on to the Narrative app; the app calls `POST /mcp-connections/complete` with the user's own bearer token, which exchanges the code and marks the connection `connected`. That last step is authenticated on purpose. The callback is public — it's a cross-site browser redirect, so no bearer reaches it — so it is not allowed to complete anything. Only the user who started the flow can turn the stored code into a token. Tokens are stored encrypted and used server-side — they are never returned by the API. Once connected, reference the connection by id from an agent run's `mcp_servers[].connection_id`. - name: App Invites description: >- App invites allow applications to create one-time, shareable links on behalf of their users. These links enable users to invite third parties who do not have a Narrative account to perform actions within the application. For example, a Narrative user can send an invite link to a third party who then completes a Pinterest OAuth flow and creates a connector profile in the inviter's account, allowing the inviter to deliver audience data to the third party's Pinterest account without the third party needing a Narrative account. This API is intended to be used by applications (via app client credentials) to create and manage invites on behalf of their users, which can then be shared with invitees. - name: Apps description: >- Apps are applications bundled with a UI that can perform various actions on behalf of a user utilizing the Narrative API. Related guides: - [Building a Narrative Native App](https://www.narrative.io/knowledge-base/how-to-guides/building-a-narrative-native-app) - name: Access Tokens description: >- System Access Tokens are long-lived bearer credentials for calling the API without a user present. A token belongs to a company, carries an explicit list of permissions, and expires on a date you choose — at least a day out and at most a year. `admin` access cannot be granted to one. `POST /access-tokens/tokens` is the only endpoint that returns the credential. Everything after that works in terms of the token's id: the list, get and update responses describe a token without ever repeating its `access_token`. If you lose it, delete the token and create another. Related guides: - [How to Create an API Token](https://www.narrative.io/knowledge-base/how-to-guides/understanding-narratives-apis/create-an-api-token) - name: Attributes description: >- An attribute models a standardized data point available for sale on the Narrative marketplace. Narrative automatically turns data points from provider datasets into attributes so that buyers can purchase well-formed, standardized data from any supplier on the marketplace. - name: Auth description: >- API token is a crucial step for developers to securely authenticate requests to the Narrative API Related guides: - [How to Create an API Token](https://www.narrative.io/knowledge-base/how-to-guides/understanding-narratives-apis/create-an-api-token) - name: Authentication description: User login and registration - name: Billings description: Used by Narrative internally to bill customers - name: Companies description: A collection of employees - name: Company Marketing Information description: Useful information related to companies - name: Compute Pools description: >- Compute pools represent compute resources (e.g. Snowflake warehouses) provisioned within a data plane. Companies can manage and share compute pools, assign them to jobs, and set a default compute pool on data planes. - name: Connections description: Associations between connectors and datasets - name: Datasets description: >- Any kind of data, in any schema, can be pushed into the Narrative Data Collaboration Platform as a dataset exactly as it is stored in your own system. The `datasets` API allows you to manage your datasets. - name: Derivations description: >- Derivation rules describe how the value of one Rosetta Stone attribute can be computed from another — for example, hashing a raw email into a SHA-256 hashed email. Each rule carries a transformation expression that reads the source attribute's value through `$source`. The `derivations` API allows you to browse the rules your company can use — the ones it owns plus the ones shared with it through collaborators. Creating and changing them requires an `admin` grant on `attribute_derivations`, and a rule can only be changed by the company that owns it. - name: Installations description: Installations of Applications for a profile - name: Jobs description: >- Jobs represent an operation done on a given data plane. All jobs today are tied to a query that represents a forecast or a materialized view. The jobs API provides an interface for interacting with the jobs table, which stores various operations involving reading or writing data. This API allows users to retrieve detailed information about specific jobs, including NQL forecasts and materialized views. - name: Mappings description: >- A mapping is a transformation from a dataset to an attribute. Defining a mapping between a dataset and an attribute makes the dataset eligible to participate in subscriptions where a buyer is purchasing the target attribute. - name: Model Inference description: Model Inference - name: Model Training description: >- Train machine learning models on datasets, e.g. text classifiers used to power attribute mappings. - name: Models description: >- Machine learning models for training and inference. Models can be stored in HuggingFace or Narrative repositories and have configurable collaborator permissions for training and inference access. The `models` API allows you to list, retrieve, and update models accessible to your company. - name: NQL description: >- Narrative Query Language (NQL) is a specialized, SQL-inspired language designed to query and manipulate data within the Narrative platform. While it looks and feels much like standard SQL, it offers extended functionality and syntax that let you leverage platform-specific features—such as referencing datasets by their IDs, creating materialized views, or generating forecasts—without having to manage the complexities of different query engines behind the scenes. NQL queries can ultimately compile down to multiple underlying engines (e.g., Snowflake, Spark) to execute your requests efficiently in the Narrative ecosystem. - name: Profiles description: >- App profiles are associated with an installation. They represent a reference to a configuration that the app can use to save confidential information outside of Narrative's control. Profiles are currently used to configure settings for connector apps. - name: Resources description: >- Narrative gives you access to managed resources, like your own AWS S3 bucket, so that you can effortlessly buy and sell data on the platform. The `resources` API allows you to manage your resources. - name: Schema Inference description: >- The `schema-inference` API analyzes submitted files to automatically infer and return their structure as a dataset schema. - name: Uploads description: >- The `uploads` API allows you to send files to Narrative and use them to perform tasks like creating a list or adding data to a dataset. - name: Usage description: >- The `usage` API enables the recording of usage events associated with a product. - name: Webhooks description: >- Webhooks push events to a URL you control instead of making you poll for them. You create a subscription with the endpoint you want events sent to and a filter describing which events you want. Two kinds of subscription exist: job subscriptions follow the lifecycle of Narrative jobs, and app subscriptions follow the events a Narrative app reports through `POST /apps/events`. Creating a subscription returns a `secret`. Narrative sends it back in the `X-Narrative-Secret` header on every delivery, and comparing the two is how you tell a real callback from a forged one — so store it and do not share it. Deliveries are described under the "Event delivery" webhook below. Return any 2xx; anything else is retried with exponential backoff, and because a retry reuses the envelope's `id`, handlers should be idempotent on it. - name: Workflows description: >- The `workflows` API allows you to create, schedule, trigger, and archive workflows. Workflows are defined using a serverlessworkflow YAML specification. paths: /data-planes/{data_plane_id}: patch: tags: - Data Planes summary: Update a data plane description: >- Update the display name and/or the description of a data plane owned by the authenticated company. Every field in the body is optional: a field that is omitted is left unchanged, and `description: null` clears the description. An empty body succeeds and changes nothing. Collaborators cannot update a data plane they do not own. operationId: updateDataPlane parameters: - name: data_plane_id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateDataPlaneRequest' responses: '200': description: OK. The updated data plane, which the caller always owns. content: application/json: schema: $ref: '#/components/schemas/DataPlaneOwnedResponse' '400': description: >- The request body is not valid — for example `display_name` is empty or whitespace-only, `display_name` is longer than 64 characters once trimmed, or `description` is longer than 2048 characters once trimmed. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- No active data plane with this id is owned by the authenticated company. The body is empty. security: - BearerAuth: [] components: schemas: UpdateDataPlaneRequest: type: object description: >- Fields to change on a data plane. Every field is optional. A field that is omitted is left unchanged. properties: display_name: description: >- New display name. Omitting it, or sending null, leaves the current name in place; the name itself is never cleared. Trimmed of surrounding whitespace; must be non-empty and at most 64 characters once trimmed. type: - string - 'null' minLength: 1 maxLength: 64 description: description: >- New description. Null clears the current description; omitting the field leaves it in place. Trimmed of surrounding whitespace; at most 2048 characters once trimmed. type: - string - 'null' maxLength: 2048 DataPlaneOwnedResponse: type: object required: - type - id - company_id - created_at - display_name - external_id - platform - status - updated_at - collaborators - compute_pools - is_narrative properties: type: type: string enum: - owned id: type: string format: uuid company_id: $ref: '#/components/schemas/CompanyId' created_at: type: string format: date-time description: type: - string - 'null' display_name: type: string external_id: type: string platform: $ref: '#/components/schemas/Platform' status: type: string enum: - active - archived last_heartbeat_at: type: - string - 'null' format: date-time tags: type: - array - 'null' items: type: string updated_at: type: string format: date-time collaborators: $ref: '#/components/schemas/DataPlaneCollaborators' default_compute_pool_id: type: - string - 'null' format: uuid compute_pools: type: array items: $ref: '#/components/schemas/ComputePoolResponse' is_narrative: description: >- True for the shared data plane Narrative operates. Use this rather than matching on `display_name`, which the owner can change. type: boolean Error: type: object required: - error - error_description properties: error: type: string example: Unauthorized error_description: type: string example: You are not authorized to use this endpoint. CompanyId: type: integer format: int64 description: The id of an existing company example: 345 Platform: oneOf: - $ref: '#/components/schemas/AwsPlatform' - $ref: '#/components/schemas/SnowflakePlatform' discriminator: propertyName: type mapping: platform_aws: '#/components/schemas/AwsPlatform' platform_snowflake: '#/components/schemas/SnowflakePlatform' DataPlaneCollaborators: type: object required: - participants - manage_compute_pools properties: participants: $ref: '#/components/schemas/DataPlaneParticipants' manage_compute_pools: $ref: '#/components/schemas/DataPlaneParticipants' ComputePoolResponse: oneOf: - $ref: '#/components/schemas/ComputePoolOwnedResponse' - $ref: '#/components/schemas/ComputePoolSharedResponse' discriminator: propertyName: type mapping: owned: '#/components/schemas/ComputePoolOwnedResponse' shared: '#/components/schemas/ComputePoolSharedResponse' AwsPlatform: type: object description: >- A data plane hosted in an AWS account. AWS data planes outside `us-east-1` currently only run (and cancel) `health_check` jobs, and don't support dataset creation yet: other such requests are rejected with a `400`. required: - type - account_id - region properties: type: type: string enum: - platform_aws account_id: type: string description: The 12-digit AWS account ID of the account hosting the data plane. pattern: ^[0-9]{12}$ region: $ref: '#/components/schemas/AwsRegion' SnowflakePlatform: type: object required: - type - account_locator - account_name - organization_name properties: type: type: string enum: - platform_snowflake account_locator: type: string account_name: type: string organization_name: type: string region: oneOf: - $ref: '#/components/schemas/Region' - type: 'null' DataPlaneParticipants: oneOf: - $ref: '#/components/schemas/ParticipantsAll' - $ref: '#/components/schemas/ParticipantsNone' - $ref: '#/components/schemas/DataPlaneParticipantsInclusion' - $ref: '#/components/schemas/DataPlaneParticipantsExclusion' discriminator: propertyName: type mapping: all: '#/components/schemas/ParticipantsAll' none: '#/components/schemas/ParticipantsNone' inclusion: '#/components/schemas/DataPlaneParticipantsInclusion' exclusion: '#/components/schemas/DataPlaneParticipantsExclusion' ComputePoolOwnedResponse: type: object required: - type - id - company_id - data_plane_id - external_id - name - display_name - status - created_at - provider - collaborators - tags - default_source properties: type: type: string enum: - owned id: type: string format: uuid company_id: $ref: '#/components/schemas/CompanyId' data_plane_id: type: string format: uuid external_id: $ref: '#/components/schemas/ExternalId' name: type: string display_name: type: string description: type: - string - 'null' status: type: string enum: - active - archived created_at: type: string format: date-time updated_at: description: Null until the pool has been updated at least once. type: - string - 'null' format: date-time tags: type: array items: type: string provider: $ref: '#/components/schemas/Provider' collaborators: $ref: '#/components/schemas/ComputePoolCollaborators' default_source: description: >- Set when this pool is the compute pool the authenticated company's jobs run on when they don't name one themselves, and says which level made it the default. `null` on every other pool. Exactly one active pool per data plane can carry a non-null value. oneOf: - $ref: '#/components/schemas/ComputePoolDefaultSource' - type: 'null' ComputePoolSharedResponse: type: object required: - type - id - company_id - data_plane_id - external_id - name - display_name - status - created_at - provider - tags - default_source properties: type: type: string enum: - shared id: type: string format: uuid company_id: $ref: '#/components/schemas/CompanyId' data_plane_id: type: string format: uuid external_id: $ref: '#/components/schemas/ExternalId' name: type: string display_name: type: string description: type: - string - 'null' status: type: string enum: - active - archived created_at: type: string format: date-time updated_at: description: Null until the pool has been updated at least once. type: - string - 'null' format: date-time tags: type: array items: type: string provider: $ref: '#/components/schemas/Provider' default_source: description: >- Set when this pool is the compute pool the authenticated company's jobs run on when they don't name one themselves, and says which level made it the default. `null` on every other pool. Exactly one active pool per data plane can carry a non-null value. oneOf: - $ref: '#/components/schemas/ComputePoolDefaultSource' - type: 'null' AwsRegion: type: object required: - type - id properties: type: type: string enum: - region_aws id: type: string description: AWS region identifier, e.g. `us-east-1`. Region: oneOf: - $ref: '#/components/schemas/AwsRegion' - $ref: '#/components/schemas/AzureRegion' - $ref: '#/components/schemas/GcpRegion' discriminator: propertyName: type mapping: region_aws: '#/components/schemas/AwsRegion' region_azure: '#/components/schemas/AzureRegion' region_gcp: '#/components/schemas/GcpRegion' ParticipantsAll: type: object required: - type properties: type: type: string enum: - all ParticipantsNone: type: object required: - type properties: type: type: string enum: - none DataPlaneParticipantsInclusion: type: object required: - type - company_ids properties: type: type: string enum: - inclusion company_ids: type: array minItems: 1 items: $ref: '#/components/schemas/CompanyId' DataPlaneParticipantsExclusion: type: object required: - type - company_ids properties: type: type: string enum: - exclusion company_ids: type: array minItems: 1 items: $ref: '#/components/schemas/CompanyId' ExternalId: oneOf: - $ref: '#/components/schemas/SnowflakeWarehouse' - $ref: '#/components/schemas/AwsEmrExternalId' discriminator: propertyName: type mapping: snowflake_warehouse: '#/components/schemas/SnowflakeWarehouse' aws_emr: '#/components/schemas/AwsEmrExternalId' Provider: oneOf: - $ref: '#/components/schemas/SnowflakeWarehouseProvider' - $ref: '#/components/schemas/AwsEmrProvider' discriminator: propertyName: type mapping: snowflake_warehouse: '#/components/schemas/SnowflakeWarehouseProvider' aws_emr: '#/components/schemas/AwsEmrProvider' ComputePoolCollaborators: type: object required: - use properties: use: $ref: '#/components/schemas/ComputePoolParticipants' description: >- Companies that can use this compute pool for jobs. Use participants automatically have view access. ComputePoolDefaultSource: description: >- Where the authenticated company's default compute pool for a data plane comes from. `company` is the company's own default for the data plane (`PUT /company/{company_id}/data-planes/{data_plane_id}/default-compute-pool/{compute_pool_id}`) and takes precedence; `data_plane` is the default set by the data plane's owner (`PUT /data-planes/{data_plane_id}/default-compute-pool/{compute_pool_id}`). type: string enum: - company - data_plane AzureRegion: type: object required: - type - id properties: type: type: string enum: - region_azure id: type: string description: Azure region identifier, e.g. `uaenorth`. GcpRegion: type: object required: - type - id properties: type: type: string enum: - region_gcp id: type: string description: GCP region identifier, e.g. `us-east4`. SnowflakeWarehouse: type: object required: - type - name - alias properties: type: type: string enum: - snowflake_warehouse name: type: string description: >- Snowflake warehouse name. Must start with a letter or underscore and contain only alphanumeric characters, underscores, and dollar signs. pattern: ^[a-zA-Z_][a-zA-Z0-9_$]*$ maxLength: 255 alias: type: string format: uuid AwsEmrExternalId: type: object required: - type properties: type: type: string enum: - aws_emr SnowflakeWarehouseProvider: type: object required: - type properties: type: type: string enum: - snowflake_warehouse warehouse_name: type: - string - 'null' description: The name of the Snowflake warehouse to use. size: type: - string - 'null' enum: - x_small - small - medium - large - x_large - 2x_large - 3x_large - 4x_large - 5x_large - 6x_large - null warehouse_type: type: - string - 'null' enum: - standard - snowpark_optimized - null auto_suspend: type: - integer - 'null' description: Auto-suspend time in seconds. auto_resume: type: - boolean - 'null' min_cluster_count: type: - integer - 'null' max_cluster_count: type: - integer - 'null' scaling_policy: type: - string - 'null' enum: - standard - economy - null max_concurrency_level: type: - integer - 'null' statement_queued_timeout_in_seconds: type: - integer - 'null' statement_timeout_in_seconds: type: - integer - 'null' enable_query_acceleration: type: - boolean - 'null' query_acceleration_max_scale_factor: type: - integer - 'null' resource_constraint: type: - string - 'null' comment: type: - string - 'null' AwsEmrProvider: type: object required: - type - size properties: type: type: string enum: - aws_emr idle_timeout_seconds: type: - integer - 'null' minimum: -1 maximum: 604800 description: > EMR cluster auto-termination idle timeout, in seconds. Tri-state semantics (applied on both create and update — omitting this field on an update resets it to the default, it does not preserve the prior value): - omitted / `null`: the pool is set to the default of 15 minutes (900 seconds). - `-1`: idle-termination disabled — EMR's `AutoTerminationPolicy` is not set on the cluster and the operator-side idle reaper skips the idle check too. The cluster runs until it is explicitly terminated or recycled. - `60` ≤ n ≤ `604800` (7 days): set EMR's `AutoTerminationPolicy` to that value, and use the same value in the operator-side idle reaper. job_execution_timeout_seconds: type: - integer - 'null' minimum: 60 maximum: 604800 description: > Maximum time, in seconds, that a single job's EMR step may stay in `RUNNING` before the operator cancels the step and fails the job. Omitted / `null` means the pool is set to the default of 4 hours (14400 seconds), on both create and update (omitting it on an update resets it to the default rather than preserving the prior value). When set explicitly, must be between 60 seconds and 7 days. The shared Narrative compute pool is configured with a 1-hour timeout and is intended for small jobs. Pools the user provisions for themselves can set their own (longer) limit. size: type: string enum: - x_small - small - medium - large - x_large - 2x_large - 3x_large - 4x_large - 5x_large - 6x_large - x_small_storage - small_storage - medium_storage - large_storage - x_large_storage - 2x_large_storage - 3x_large_storage - 4x_large_storage - 5x_large_storage - 6x_large_storage description: > Compute pool size. Names mirror Snowflake's warehouse sizes and target the equivalent Snowflake warehouse's *memory* budget — a workload that fits in a Snowflake warehouse of size N gets equivalent RAM on the EMR cluster of size N. vCPU counts will not match Snowflake's because EMR runs on memory-optimized instances (r7g/r7gd/r6g, 8 GiB/vCPU), so the same memory budget delivers fewer vCPUs than Snowflake. Target worker (core+task) memory at max scale: x_small (~32 GiB, ~4 vCPU; min size — overshoots Snowflake's 16 GiB), small (~32 GiB, ~4 vCPU), medium (~64 GiB, ~8 vCPU), large (~128 GiB, ~16 vCPU), x_large (~256 GiB, ~32 vCPU), 2x_large (~512 GiB, ~64 vCPU), 3x_large (~1 TiB, ~128 vCPU), 4x_large (~2 TiB, ~256 vCPU), 5x_large (~4 TiB, ~512 vCPU), 6x_large (~8 TiB, ~1024 vCPU). Each size has a `*_storage` variant (e.g. `medium_storage`) with the same memory budget, but running on `rXgd` instances with local NVMe SSD storage. Use these for shuffle-/scratch-heavy jobs that would otherwise spill to EBS and fail with "No space left on device". ComputePoolParticipants: oneOf: - $ref: '#/components/schemas/ParticipantsAll' - $ref: '#/components/schemas/ParticipantsNone' - $ref: '#/components/schemas/ParticipantsInclusion' - $ref: '#/components/schemas/ParticipantsExclusion' discriminator: propertyName: type mapping: all: '#/components/schemas/ParticipantsAll' none: '#/components/schemas/ParticipantsNone' inclusion: '#/components/schemas/ParticipantsInclusion' exclusion: '#/components/schemas/ParticipantsExclusion' ParticipantsInclusion: type: object required: - type - company_ids properties: type: type: string enum: - inclusion company_ids: type: array minItems: 1 items: $ref: '#/components/schemas/CompanyId' ParticipantsExclusion: type: object required: - type - company_ids properties: type: type: string enum: - exclusion company_ids: type: array minItems: 1 items: $ref: '#/components/schemas/CompanyId' securitySchemes: BearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.