> ## Documentation Index > Fetch the complete documentation index at: https://docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update Document Metadata > Merges keys into a document's `user_metadata` and returns the updated document. Unlike the other operations on this path, it takes the document ID, not a document file ID. Send the document's `row_version` as `expectedRowVersion`. Read the document right before updating it, and on `409` read it again and resend. ## OpenAPI ````yaml /en/api-reference/openapi_service.json patch /knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id} openapi: 3.0.1 info: description: >- REST API for Dify applications and knowledge bases. Application endpoints authenticate with an app API key; knowledge endpoints authenticate with a dataset API key. title: Dify Service API version: 1.0.0 servers: - description: >- Base URL of the Dify Service API. For self-hosted deployments, replace it with your own API base URL. url: https://{api_base_url} variables: api_base_url: default: api.dify.ai/v1 description: Host and path of the API base URL, without the `https://` prefix. security: - ApiKeyAuth: [] tags: - description: Operations related to chat messages and interactions. name: Chat Messages - description: File upload and preview operations. name: Files - description: Operations related to end user information. name: End Users - description: User feedback operations. name: Feedback - description: Operations related to managing conversations. name: Conversations - description: Text-to-Speech and Speech-to-Text operations. name: Audio - description: Operations to retrieve application settings and information. name: Applications - description: Operations related to managing annotations for direct replies. name: Annotations - description: Endpoints for resuming paused workflows that require human input. name: Human Input - description: Operations for executing and managing workflows. name: Workflow Runs - description: Operations related to text generation and completion. name: Completion Messages - description: >- Operations for managing knowledge bases, including creation, configuration, and retrieval. name: Knowledge Bases - description: >- Operations for creating, updating, and managing documents within a knowledge base. name: Documents - description: Operations for managing document chunks and child chunks. name: Chunks - description: >- Operations for managing knowledge base metadata fields and document metadata values. name: Metadata - description: Operations for managing knowledge base tags and tag bindings. name: Tags - description: Operations for retrieving available models. name: Models - description: >- Operations for managing and running knowledge pipelines, including datasource plugins and pipeline execution. name: Knowledge Pipeline - description: Ask a knowledge base a question and stream the answer. name: Queries - description: Inspect what a query retrieved and why. name: Query Records - description: Run a research question in the background and collect its results. name: Research Tasks - description: >- Read the documents in a knowledge base, their files, revisions, and chunks; label documents with metadata. name: Documents and Chunks - description: >- Follow, cancel, or retry indexing, and list the knowledge base's background tasks. name: Indexing Tasks - description: >- Follow the deletion of a document file, a batch of files, or a source until it finishes. name: Deletion Jobs - description: >- Manage the sources that feed a knowledge base, their sync schedules, and their connections. name: Sources - description: >- Sync a source now, import website pages or provider items, and follow, cancel, or retry the runs. name: Source Syncs and Imports - description: >- Read and change the knowledge base's models and retrieval settings, and follow the migration a change starts. name: Settings paths: /knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}: patch: tags: - Documents and Chunks summary: Update Document Metadata description: >- Merges keys into a document's `user_metadata` and returns the updated document. Unlike the other operations on this path, it takes the document ID, not a document file ID. Send the document's `row_version` as `expectedRowVersion`. Read the document right before updating it, and on `409` read it again and resend. operationId: updateDocumentMetadata parameters: - description: >- Knowledge base ID: the last segment of the Service API endpoint shown in the knowledge base's **API Access** dialog (`…/knowledge-fs/spaces/`), and the segment after `/datasets/new/` in the address bar. in: path name: knowledge_base_id required: true schema: format: uuid type: string - description: >- The document ID: `id` from [List Documents](/en/api-reference/documents-and-chunks/list-documents) or [Get Document](/en/api-reference/documents-and-chunks/get-document), or `document_id` from [Get Document by File](/en/api-reference/documents-and-chunks/get-document-by-file). Not a document file ID, even though [Get Document File](/en/api-reference/documents-and-chunks/get-document-file) and [Delete Document File](/en/api-reference/documents-and-chunks/delete-document-file) take one on this path. A document file ID answers `404`. in: path name: document_file_id required: true schema: format: uuid type: string requestBody: content: application/json: examples: request: summary: Request Example value: expectedRowVersion: 4 patch: owner: billing-team review_date: '2027-03-01T00:00:00Z' schema: additionalProperties: false properties: expectedRowVersion: description: >- The document's current `row_version`, from [Get Document](/en/api-reference/documents-and-chunks/get-document) or [List Documents](/en/api-reference/documents-and-chunks/list-documents), or the `row_version` this operation last returned. A newly active revision and enabling or disabling the document in Dify also change it, so read it right before updating. A stale value answers `409` and nothing changes. minimum: 0 type: integer patch: additionalProperties: true description: >- Keys to merge into `user_metadata`: - A key with a value sets that key. - A key with `null` removes it. - Keys you leave out stay as they are. Each key names a metadata field, in lowercase snake case. The field must already exist: create it in Dify first. The value must match the field's type: a string for `string`, a finite number for `number`, and a UTC timestamp such as `2026-12-01T00:00:00Z` for `time`. Reserved keys answer `400`: `activeRevision`, `contentHash`, `documentAssetId`, `documentAssetVersion`, `mimeType`, `provenance`, `providerItemId`, `sourceId`, `system`, `systemMetadata`, `tenantId`, `__knowledgeFs`, and keys starting with `system.`, `provenance.`, or `__knowledgeFs.`. type: object required: - expectedRowVersion - patch type: object description: >- The normalized request must fit within 131,072 UTF-8 bytes. See [Request Size Limits](/en/api-reference/guides/knowledge-base#request-size-limits). required: true responses: '200': content: application/json: examples: success: summary: Response Example value: active: activated_at: '2026-10-20T08:16:05Z' content_hash: >- 4f7c2d9a1b3e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4 created_at: '2026-10-20T08:15:42Z' document_asset_id: 6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b document_asset_version: 1 document_id: 2f6b8d1a-7c3e-4a5b-9d0e-1f2a3b4c5d6e knowledge_space_id: 9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b mime_type: application/pdf revision: 2 size_bytes: 482113 state: active active_revision: 2 created_at: '2026-09-03T10:02:11Z' disabled_at: null disabled_by_subject_id: null enabled: true id: 2f6b8d1a-7c3e-4a5b-9d0e-1f2a3b4c5d6e knowledge_space_id: 9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b latest_task: null provider_item_id: null row_version: 5 source_id: null status: ready title: handbook.pdf updated_at: '2026-10-21T02:40:13Z' user_metadata: owner: billing-team product_line: billing review_date: '2027-03-01T00:00:00Z' schema: $ref: '#/components/schemas/KnowledgeBaseDocument' description: >- The updated document. Its `row_version` is the value to send on the next update, and `latest_task` is always `null` in this response. '400': content: application/json: examples: knowledge_fs_invalid_request_local: summary: knowledge_fs_invalid_request (request validation) value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 violations: - field: - patch type: missing knowledge_fs_invalid_request_path: summary: knowledge_fs_invalid_request (path ID) value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 knowledge_fs_invalid_request_upstream: summary: knowledge_fs_invalid_request (rejected) value: code: knowledge_fs_invalid_request failure: category: validation code: KNOWLEDGE_FS_INVALID_REQUEST message: The Agent Knowledge Base request is invalid. retryPolicy: never traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: The Agent Knowledge Base request is invalid. status: 400 description: >- - `knowledge_fs_invalid_request`: the request failed validation. `violations` names each failing field. A missing `patch` or `expectedRowVersion`, or any other body key, answers `400`. - `knowledge_fs_invalid_request`: `patch` uses a reserved key, names a metadata field the knowledge base doesn't have, or gives a field a value of the wrong type. The body carries error details in `failure`, which does not say which key was rejected. - `knowledge_fs_invalid_request`: `document_file_id` is not a UUID. - `knowledge_fs_invalid_request`: `document_file_id` is malformed. '401': content: application/json: examples: knowledge_fs_invalid_credential: summary: knowledge_fs_invalid_credential value: code: knowledge_fs_invalid_credential message: Invalid Agent Knowledge Base service credential. status: 401 unauthorized: summary: unauthorized value: code: unauthorized message: Access token is invalid status: 401 description: >- - `unauthorized`: the `Authorization` header is missing, or the key is unknown or not a knowledge base API key. - `knowledge_fs_invalid_credential`: the key is valid, but no knowledge base with this ID exists in the key's workspace, or the key is not tied to a workspace. '403': content: application/json: examples: forbidden: summary: forbidden (rate limit) value: code: forbidden message: >- Sorry, you have reached the knowledge base request rate limit of your subscription. status: 403 knowledge_fs_access_denied_scope: summary: knowledge_fs_access_denied (key scope) value: code: knowledge_fs_access_denied message: Agent Knowledge Base operation is not allowed. status: 403 knowledge_fs_access_denied_upstream: summary: knowledge_fs_access_denied (rejected) value: code: knowledge_fs_access_denied failure: action: contact_admin category: authorization code: KNOWLEDGE_FS_ACCESS_DENIED message: >- You do not have permission to perform this Agent Knowledge Base operation. retryPolicy: never traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: >- You do not have permission to perform this Agent Knowledge Base operation. status: 403 description: >- - `knowledge_fs_access_denied`: the key is scoped to other knowledge bases, **API access** is off for this knowledge base, or the knowledge base is not active. - `knowledge_fs_access_denied`: the key has no access to this knowledge base's content. - `forbidden`: on Dify Cloud, the workspace has reached the knowledge base request rate limit of its subscription. Every call counts, reads included. '404': content: application/json: examples: knowledge_fs_resource_not_found: summary: knowledge_fs_resource_not_found value: code: knowledge_fs_resource_not_found failure: category: not_found code: KNOWLEDGE_FS_NOT_FOUND message: >- The requested Agent Knowledge Base resource was not found. retryPolicy: never traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: The requested Agent Knowledge Base resource was not found. status: 404 not_found: summary: not_found (feature off) value: code: not_found message: >- The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again. status: 404 description: >- - `knowledge_fs_resource_not_found`: no document has this ID, the key cannot read it, or the document's file or its source is being deleted. - `not_found`: the Agent Knowledge Base feature is turned off on this deployment. '409': content: application/json: examples: logical_document_cas_conflict: summary: knowledge_fs_conflict (stale row version) value: code: knowledge_fs_conflict failure: action: retry category: conflict code: LOGICAL_DOCUMENT_CAS_CONFLICT message: >- The Agent Knowledge Base operation conflicts with the current resource state. parameters: currentRowVersion: 5 expectedRowVersion: 4 retryPolicy: manual traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: >- The Agent Knowledge Base operation conflicts with the current resource state. status: 409 description: >- - `knowledge_fs_conflict`: `expectedRowVersion` is not the document's current `row_version`, for example because a new revision became active or another update landed first. `failure.code` is `LOGICAL_DOCUMENT_CAS_CONFLICT`, and `failure.parameters.currentRowVersion` carries the current value. Read the document again, check that your change still applies, and resend with the current `row_version`. '413': content: application/json: examples: knowledge_fs_request_too_large: summary: knowledge_fs_request_too_large (request budget) value: code: knowledge_fs_request_too_large message: Agent Knowledge Base request is too large. status: 413 description: >- - `knowledge_fs_request_too_large`: the request, once Dify adds its defaults, exceeds 131,072 UTF-8 bytes. See [Request Size Limits](/en/api-reference/guides/knowledge-base#request-size-limits). '502': content: application/json: examples: knowledge_fs_upstream_unavailable: summary: knowledge_fs_upstream_unavailable (service error) value: code: knowledge_fs_upstream_unavailable failure: action: contact_admin category: internal code: KNOWLEDGE_FS_INTERNAL_ERROR message: >- Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference. status: 502 knowledge_fs_upstream_unavailable_transport: summary: knowledge_fs_upstream_unavailable (no response) value: code: knowledge_fs_upstream_unavailable message: Agent Knowledge Base is unavailable. status: 502 description: >- - `knowledge_fs_upstream_unavailable`: no answer came back in time, or the answer couldn't be read. The update may have landed. Read the document with [Get Document](/en/api-reference/documents-and-chunks/get-document) and compare `user_metadata` before resending. A resend with the old `expectedRowVersion` answers `409` if the first call landed. '503': content: application/json: examples: knowledge_fs_operation_unavailable: summary: knowledge_fs_operation_unavailable value: code: knowledge_fs_operation_unavailable message: Agent Knowledge Base operation is not available. status: 503 knowledge_fs_operation_unavailable_upstream: summary: knowledge_fs_operation_unavailable (temporary) value: code: knowledge_fs_operation_unavailable failure: action: retry category: dependency code: KNOWLEDGE_FS_UNAVAILABLE message: >- A service required by Agent Knowledge Base is temporarily unavailable. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- A service required by Agent Knowledge Base is temporarily unavailable. status: 503 description: >- - `knowledge_fs_operation_unavailable`: the Agent Knowledge Base feature is not set up for this workspace, this operation is not available on the deployment, or the key's access to this knowledge base changed while the request was being authorized. - `knowledge_fs_operation_unavailable`: the request can't be served right now. Follow `failure.retryPolicy`. components: schemas: KnowledgeBaseDocument: properties: active: allOf: - $ref: '#/components/schemas/KnowledgeBaseDocumentRevision' description: >- The active revision: the content the knowledge base serves. Pass its `revision` to [List Chunks](/en/api-reference/documents-and-chunks/list-chunks) and its `document_asset_id` to [Get Document File](/en/api-reference/documents-and-chunks/get-document-file). `null` while no revision is active. nullable: true active_revision: description: Number of the active revision. `null` while none is active. nullable: true type: integer created_at: description: When the document was created, ISO 8601. type: string disabled_at: description: When the document was disabled in Dify, ISO 8601. nullable: true type: string disabled_by_subject_id: description: >- Internal ID of whoever disabled the document. Not needed to call this API. nullable: true type: string enabled: description: >- `false` after the document is disabled in Dify. [Re-index Documents](/en/api-reference/documents-and-chunks/re-index-documents) skips disabled documents. type: boolean id: description: >- Document ID. It stays the same when the document's content is updated. type: string knowledge_space_id: description: >- Internal ID of the knowledge base. Not the knowledge base ID in the path. type: string latest_task: allOf: - $ref: '#/components/schemas/KnowledgeBaseBackgroundTask' description: >- The newest indexing task behind the document's revisions, with `task_kind: document`. Follow it with [Get Document Indexing Task](/en/api-reference/indexing-tasks/get-document-indexing-task) using its `id`. `null` when there is none, and always `null` in the [Update Document Metadata](/en/api-reference/documents-and-chunks/update-document-metadata) response. nullable: true provider_item_id: description: >- For a document imported from a source, the item's identifier there: the `providerItemId` sent to [Import Source Items](/en/api-reference/source-syncs-and-imports/import-source-items), or the `page_id` of a website page. nullable: true type: string row_version: description: >- Change counter. Send it as `expectedRowVersion` on [Update Document Metadata](/en/api-reference/documents-and-chunks/update-document-metadata). It increases on metadata updates, when a new revision becomes active, and when the document is enabled or disabled in Dify. type: integer source_id: description: Source the document came from. `null` for uploaded files. nullable: true type: string status: description: >- `pending` (no revision active yet), `ready` (a revision is active), `failed` (the first revision failed to index and none is active), or `deleting`. A `ready` document stays `ready` when a later revision fails. type: string title: description: Document title. type: string updated_at: description: When the document last changed, ISO 8601. type: string user_metadata: additionalProperties: true description: >- Custom metadata, keyed by metadata field name. Change it with [Update Document Metadata](/en/api-reference/documents-and-chunks/update-document-metadata) or in Dify. type: object type: object KnowledgeBaseDocumentRevision: properties: activated_at: description: >- When the revision became active, ISO 8601. `null` for a revision that never became active. nullable: true type: string content_hash: description: SHA-256 hash of the content, hex-encoded. type: string created_at: description: When the revision was created, ISO 8601. type: string document_asset_id: description: >- ID of the document file behind this revision. Use it with [Get Document File](/en/api-reference/documents-and-chunks/get-document-file). type: string document_asset_version: description: The document file's `version` when this revision was created. type: integer document_id: description: >- Document ID: the `id` of [Get Document](/en/api-reference/documents-and-chunks/get-document). type: string knowledge_space_id: description: >- Internal ID of the knowledge base. Not the knowledge base ID in the path. type: string mime_type: description: MIME type of the document file. type: string revision: description: >- Revision number, starting at `1`. The `revision` path value for [List Chunks](/en/api-reference/documents-and-chunks/list-chunks). type: integer size_bytes: description: Size of the document file in bytes. type: integer state: description: >- `candidate` while the revision is being indexed, `active` for the revision the knowledge base serves, `superseded` after a newer revision became active, `failed` when indexing failed. type: string type: object KnowledgeBaseBackgroundTask: properties: can_cancel: description: >- Whether the task can be canceled now. For `task_kind: document`, cancel it with [Cancel Indexing Task](/en/api-reference/indexing-tasks/cancel-indexing-task) using `id`. A bulk task has no cancel operation in this API, even when `can_cancel` is `true`. type: boolean can_retry: description: >- Whether the task can be retried now. For `task_kind: document`, retry it with [Retry Indexing Task](/en/api-reference/indexing-tasks/retry-indexing-task) using `id`. That operation accepts only `failed` or `canceled` tasks, while `can_retry` is also `true` for a `completed` indexing task whose semantic enrichment failed. type: boolean completed_at: description: When the task ended, ISO 8601. `null` while it runs. nullable: true type: string created_at: description: When the task was created, ISO 8601. type: string document_id: description: >- Document ID of an indexing task. For a bulk task, set only when it has one document. nullable: true type: string document_revision: description: Revision an indexing task builds. nullable: true type: integer document_title: description: Document title, set only for a bulk task with one document. nullable: true type: string error_code: description: Error code when `state` is `failed`. nullable: true type: string error_message: description: The message for `error_code`. Can differ from `failure.message`. nullable: true type: string failure: allOf: - $ref: '#/components/schemas/KnowledgeBaseErrorDetails' description: Error details when `state` is `failed`. `null` otherwise. nullable: true failures: description: >- For a bulk task, one entry per document that failed. `null` for other kinds. items: properties: document_id: description: Document ID. type: string document_title: description: Document title. nullable: true type: string error_code: description: Error code of the failure. type: string error_message: description: The message for `error_code`. type: string failure: $ref: '#/components/schemas/KnowledgeBaseErrorDetails' job_id: description: ID of the document's task, when there is one. nullable: true type: string type: object nullable: true type: array id: description: >- Task ID: an indexing task ID for `task_kind: document`, a bulk task ID for `document_bulk`, or a source run ID for `source`. type: string knowledge_space_id: description: >- Internal ID of the knowledge base. Not the knowledge base ID in the path. type: string operation: description: >- What the task does: - `document_processing`: an indexing task. - `document_reindex`, `document_upload`, `document_delete`: a bulk task. Bulk uploads and deletions come from Dify; a deletion over this API creates a deletion job instead. - `source_sync`, `source_crawl_preview`, `source_crawl_import`, `source_online_document_import`, `source_online_drive_import`: a source run. type: string progress_completed: description: >- Items completed: the document of an indexing task, the documents of a bulk task, or the items of a source run. type: integer progress_failed: description: Items that failed, counted like `progress_completed`. type: integer progress_percent: description: >- Progress from 0 to 100. For an indexing task it follows the task's stage. type: integer progress_total: description: >- Items in the task, counted like `progress_completed`. `1` for an indexing task. type: integer semantic_enrichment: allOf: - $ref: '#/components/schemas/KnowledgeBaseSemanticEnrichment' description: >- Knowledge graph building status for an indexing task's content. Deep and Research searches follow the knowledge graph. `null` for other kinds. nullable: true source_id: description: Source of a source run. nullable: true type: string source_title: description: >- Name of the source of a source run. Set only when listing without `task_ids`. nullable: true type: string state: description: >- `queued`, `running`, `completed`, `failed`, or `canceled`, mapped from the task's own state: - An indexing task is `completed` once it has published, even while its semantic enrichment is still running. - A crawl preview waiting for its pages to be selected is `completed`. For the exact state, read an indexing task with [Get Indexing Task](/en/api-reference/indexing-tasks/get-indexing-task) and a source run with [Get Source Run](/en/api-reference/source-syncs-and-imports/get-source-run). type: string task_kind: description: >- `document` (an indexing task), `document_bulk` (a bulk task), or `source` (a source run). type: string updated_at: description: When the task last changed, ISO 8601. type: string type: object KnowledgeBaseErrorDetails: properties: action: description: >- Suggested next step, when there is one: `configure_model`, `configure_parser`, `configure_source`, `contact_admin`, `reupload`, or `retry`. `null` when not applicable; omitted from HTTP error bodies. nullable: true type: string category: description: >- Kind of failure: `authorization`, `canceled`, `configuration`, `conflict`, `dependency`, `internal`, `not_found`, `rate_limit`, `timeout`, or `validation`. type: string code: description: >- Stable error code in upper snake case, for example `KNOWLEDGE_FS_CONFLICT` or `SOURCE_CREDENTIAL_TEST_FAILED`. type: string message: description: >- Public message for the error code or failure category. Provider error details are not exposed. type: string parameters: additionalProperties: true description: >- Up to 8 values that qualify the failure, with keys among `attempt`, `currentRowVersion`, `documentCount`, `expectedRowVersion`, `fileSizeBytes`, `limit`, `maxFileSizeBytes`, `maxItems`, `modelType`, `providerKind`, `retryAfterSeconds`, and `status`. `null` when there are none; omitted from HTTP error bodies. nullable: true type: object retryPolicy: description: >- Whether a retry can help: `automatic` (the service retries on its own), `manual` (retry yourself), `after_configuration` (fix the knowledge base's setup in Dify first), or `never` (change the request). type: string stage: description: >- Stage the failure belongs to, for example `query_generation` or `credential-test`. `null` when not applicable; omitted from HTTP error bodies. nullable: true type: string traceId: description: >- Reference to quote when contacting an administrator. May be `null` in a successful response containing failure details, or omitted from an HTTP error body. nullable: true type: string type: object KnowledgeBaseSemanticEnrichment: properties: error_code: description: Error code when `state` is `failed`. nullable: true type: string error_message: description: The message for `error_code`. Can differ from `failure.message`. nullable: true type: string failure: allOf: - $ref: '#/components/schemas/KnowledgeBaseErrorDetails' description: Error details when `state` is `failed`. `null` otherwise. nullable: true nodes_completed: description: >- Knowledge graph nodes built: `0` until `state` is `ready`, then the same as `nodes_total`. type: integer nodes_total: description: Knowledge graph nodes to build. `null` until known. nullable: true type: integer provider_calls: description: Model calls made so far. nullable: true type: integer provider_calls_maximum: description: Most model calls knowledge graph building may make. nullable: true type: integer state: description: >- `not_scheduled`, `pending`, `running`, `ready`, `failed`, or `disabled`. Knowledge graph building can still be `pending` or `running` after the indexing task has published its revision. type: string updated_at: description: When the enrichment last changed, ISO 8601. nullable: true type: string type: object securitySchemes: ApiKeyAuth: bearerFormat: API_KEY description: >- Every request authenticates with an API key: `Authorization: Bearer {API_KEY}`. App endpoints take an app API key; knowledge endpoints take a knowledge base API key ([Get Started](/en/api-reference/guides/get-started)). Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP `401` (`unauthorized`). scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.