> ## Documentation Index > Fetch the complete documentation index at: https://developers.datagrid.com/llms.txt > Use this file to discover all available pages before exploring further. # Update knowledge > Update a knowledge's attributes. Each request can include either `files` or `sync`, but not both, and `files` cannot be combined with `semantic_indexing_enabled: true` — upload files first, then enable indexing in a separate request. When `files` are provided, all existing data is replaced and a re-processing pipeline runs asynchronously — this consumes credits based on the volume of data processed. Setting `semantic_indexing_enabled` to `true` on SQL-only knowledge is a one-way upgrade: it enables semantic indexing, consumes credits, and triggers an asynchronous backfill of existing records. If the upgrade is persisted but the backfill fails to start, the request returns `503` — retry the backfill with `POST /v1/knowledge/{knowledge_id}/reindex` (repeating the PATCH will not re-trigger it, because indexing is already enabled). Metadata-only and sync-only updates do not consume credits and are not blocked by credit eligibility checks. If the asynchronous processing run later fails, subsequent retrievals surface that terminal state through `status` and `last_error`. ## Upload size limits Files added in a multipart update must respect your plan’s per-file size limit. Oversized files receive **413** (`payload_too_large`); see [Knowledge upload limits](https://developers.datagrid.com/knowledge/upload-limits.md) for typical caps and strategies. ## OpenAPI ````yaml patch /knowledge/{knowledge_id} openapi: 3.0.3 info: version: 0.1.1 title: Datagrid API description: Datagrid API servers: - url: https://api.datagrid.com/v1 security: - BearerAuth: [] paths: /knowledge/{knowledge_id}: patch: tags: - Knowledge summary: Update knowledge description: >- Update a knowledge's attributes. Each request can include either `files` or `sync`, but not both, and `files` cannot be combined with `semantic_indexing_enabled: true` — upload files first, then enable indexing in a separate request. When `files` are provided, all existing data is replaced and a re-processing pipeline runs asynchronously — this consumes credits based on the volume of data processed. Setting `semantic_indexing_enabled` to `true` on SQL-only knowledge is a one-way upgrade: it enables semantic indexing, consumes credits, and triggers an asynchronous backfill of existing records. If the upgrade is persisted but the backfill fails to start, the request returns `503` — retry the backfill with `POST /v1/knowledge/{knowledge_id}/reindex` (repeating the PATCH will not re-trigger it, because indexing is already enabled). Metadata-only and sync-only updates do not consume credits and are not blocked by credit eligibility checks. If the asynchronous processing run later fails, subsequent retrievals surface that terminal state through `status` and `last_error`. operationId: Knowledge.updateKnowledge parameters: - name: knowledge_id in: path required: true schema: type: string description: The id of the knowledge to update. requestBody: required: true content: multipart/form-data: schema: type: object properties: name: type: string description: The new name for the `knowledge`. nullable: true scope: $ref: '#/components/schemas/KnowledgeScope' nullable: true parent: $ref: '#/components/schemas/ParentObject' description: Move the knowledge to a different parent page. nullable: true files: type: array items: type: string format: binary nullable: true description: >- The files to replace existing knowledge. When provided, all existing data will be removed from the knowledge and replaced with these files. Supported media types are `pdf`, `json`, `csv`, `text`, `png`, `jpeg`, `excel`, `google sheets`, `docx`, `pptx`. Cannot be used together with `sync` in the same request. sync: type: object nullable: true description: >- Sync configuration updates for knowledge created from a connection. Note: For multipart/form-data, this should be sent as a JSON string. Cannot be used together with `files` in the same request. properties: enabled: type: boolean description: Enable or disable syncing data from the connection trigger: $ref: '#/components/schemas/CronBasedTrigger' description: >- Update the trigger to a cron schedule. Only CronBasedTrigger is supported for updates. semantic_indexing_enabled: type: boolean description: >- Whether semantic indexing is enabled for this knowledge. Set to `true` to upgrade SQL-only knowledge so existing and future records are semantically indexed. This transition is one-way: setting `false` is rejected, as is combining it with `files`. Omitted leaves indexing unchanged. Already-indexed knowledge is a no-op. nullable: true responses: '200': description: Successfully updated knowledge content: application/json: schema: $ref: '#/components/schemas/Knowledge' '402': description: >- Credit limit exceeded. When a PATCH request includes files or enables semantic indexing on SQL-only knowledge, the organization must have enough credits to perform the operation and must not have reached the monthly credit cap set in Control Tower. Check your billing status, or wait for the cap to reset. '404': description: >- Not found. The requested knowledge does not exist, or the authenticated user does not have permission to access it. '413': description: > Payload too large. A file in the multipart body exceeds the per-file byte cap for the the teamspace's current plan. '429': description: >- Rate limit exceeded. The request has been throttled because the rate limit for this endpoint has been reached. Check the `Retry-After` response header and retry after the specified number of seconds. content: application/json: schema: $ref: '#/components/schemas/RateLimitError' '503': description: >- Service unavailable. Semantic indexing was enabled and persisted, but the backfill of existing records could not be started. Retry the backfill with `POST /v1/knowledge/{knowledge_id}/reindex`. components: schemas: KnowledgeScope: type: string enum: - teamspace - organization description: >- The visibility scope of the knowledge. 'teamspace' means visible only within the owning teamspace. 'organization' means visible across all teamspaces in the same organization. ParentObject: type: object description: >- The parent object, indicating where the object is located in the hierarchy oneOf: - $ref: '#/components/schemas/ParentPage' - $ref: '#/components/schemas/RootPage' CronBasedTrigger: type: object description: A cron-based schedule for syncing data required: - type - cron_expression properties: type: type: string enum: - cron description: The trigger type, which is always `cron`. cron_expression: type: string description: Cron expression (e.g., '0 0 * * *' for daily at midnight) example: 0 0 * * * pattern: ^[0-9*/-]+ [0-9*/-]+ [0-9*/-]+ [0-9*/-]+ [0-9*/-]+$ timezone: type: string description: >- IANA timezone (e.g., 'America/New_York'). Defaults to 'UTC' if not provided. example: America/New_York default: UTC description: type: string nullable: true description: Human-readable description of the schedule Knowledge: type: object description: >- The `knowledge` object represents knowledge that an agent may leverage to respond. required: - object - id - name - created_at - status - last_error - row_counts - credits - sync - parent - teamspace_id - scope - default_indexing_quality properties: object: type: string enum: - knowledge description: The object type, which is always `knowledge`. id: type: string description: >- The knowledge identifier, which can be referenced in the API endpoints. name: type: string description: The name of the knowledge. teamspace_id: type: string description: The ID of the teamspace that owns this knowledge. scope: $ref: '#/components/schemas/KnowledgeScope' default_indexing_quality: nullable: true description: >- The knowledge-level indexing override. `none` means semantic indexing is disabled; `null` means Datagrid uses its normal indexing defaults. allOf: - $ref: '#/components/schemas/DefaultIndexingQuality' parent: $ref: '#/components/schemas/ParentObject' created_at: type: string format: date-time description: The ISO string for when the knowledge was created. updated_at: type: string format: date-time description: The ISO string for when the knowledge was last updated. status: $ref: '#/components/schemas/KnowledgeStatus' last_error: nullable: true description: >- The last terminal processing error for this knowledge, if any. Present when the latest asynchronous processing or re-index run ended unsuccessfully; `null` when the knowledge is `failed` only because every row ended in a persistent failed state. allOf: - $ref: '#/components/schemas/KnowledgeLastError' row_counts: type: object description: Row count statistics for the knowledge. required: - total - completed - failed properties: total: type: number description: The total number of rows in the knowledge. completed: type: number description: The number of rows successfully learned. failed: type: number description: The number of rows that failed to be processed for learning. credits: nullable: true description: >- Credit consumption for this knowledge. `null` when the knowledge is still being processed and the final cost is not yet known (e.g. immediately after creation or reindexing), or when the credit lookup fails. When present, `consumed` is the current summed spend for the knowledge's active tables — it is not necessarily the cost of the most recent request, nor the full lifetime spend. allOf: - $ref: '#/components/schemas/OperationCredits' sync: nullable: true description: Sync information for knowledge that syncs data from a connection allOf: - $ref: '#/components/schemas/KnowledgeSync' RateLimitError: type: object description: >- Returned when the rate limit is exceeded. Rate limits are enforced per teamspace, endpoint path, and HTTP method over a 60-second sliding window. Each endpoint may have its own limit — check the X-RateLimit-Limit response header for the effective value. required: - error - message - retryable - status_code properties: status_code: type: integer description: The HTTP status code (429). statusCode: type: integer deprecated: true description: Deprecated. Use status_code instead. error: type: string enum: - rate_limit_exceeded description: The error code identifying this as a rate limit error. message: type: string description: A human-readable error message. mitigation: type: string description: Suggested action to resolve the error. retryable: type: boolean description: Whether the request can be retried after a delay. details: type: object properties: reason: type: string description: A detailed explanation of why the rate limit was exceeded. ParentPage: type: object description: The parent page reference, indicating where this page is nested required: - type - page_id properties: type: type: string enum: - page description: The type of parent. 'page' indicates nested under a specific page page_id: type: string description: The ID of the parent page. Required when type is 'page' RootPage: type: object description: The root level object required: - type properties: type: type: string enum: - root description: The type of parent. 'root' indicates at the root level DefaultIndexingQuality: type: string enum: - none KnowledgeStatus: type: string enum: - pending - partial - ready - failed description: >- The current knowledge status. `pending` indicates that processing has started but no rows have reached a terminal state yet (none learned, none failed). `partial` indicates that processing has not finished for every row — some rows may already be learned or failed while others are still being processed. `ready` indicates that processing has finished and the knowledge is available for use; some individual rows may have failed to process, so check `row_counts.failed`. `failed` indicates that no rows are currently available and the knowledge reached a terminal failure state, either because the latest asynchronous processing or re-index run ended unsuccessfully before any rows became available, or because every row ended in a persistent failed state. KnowledgeLastError: type: object required: - code - message properties: code: type: string enum: - out_of_credits - unauthorized - processing_error description: >- A machine-readable error code for the most recent terminal processing failure. message: type: string description: >- A human-readable description of the most recent terminal processing failure. OperationCredits: type: object required: - consumed properties: consumed: type: number description: The number of credits consumed by the operation. KnowledgeSync: type: object description: Sync information for knowledge that syncs data from a connection required: - connection_id - enabled properties: connection_id: type: string description: The ID of the connection used for syncing data to this knowledge example: config_123abc enabled: type: boolean description: Whether data syncing from the connection is enabled trigger: nullable: true description: >- The cron schedule configuration for syncing data from the connection. allOf: - $ref: '#/components/schemas/CronBasedTrigger' securitySchemes: BearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.