Skip to main content
GET
Export one knowledge namespace
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

GET /api/v2/knowledge/export requires an authenticated Platform API key, MCP key, or External App credential with knowledge:manage. MCP hosts call it through forge_call_operation with operationId exportKnowledge. Provide scopeType and, for every scope except company and global, a nonempty scopeId as query parameters. The namespace must be in the credential’s readable set. The endpoint has no default namespace and does not accept reader, actor, or namespace parameters. includeDeleted is optional, true or false, and defaults to false. With includeDeleted=true, the file also carries the namespace’s deleted entries (tombstones) as metadata only: entryId, namespace, status: "deleted", title, contentType, sourceType, createdAt and deletedAt, plus caseKey, grade, runId, agentId and updatedAt when the entry has them. A tombstone never carries content. An invalid query (an unknown or repeated parameter, or an includeDeleted other than true or false) answers 400 bad_request; a namespace outside the readable set answers 403 forbidden. The response is a JSON envelope containing data.storageId, data.downloadUrl, data.rowCount, and data.expiresAt (Unix epoch milliseconds), plus meta.requestId. Fetch downloadUrl separately to download the NDJSON file. The Convex storage URL expires 24 hours after issue, and Forge schedules cleanup of the stored file. Each line contains one entry: an active entry with its full text, or, with includeDeleted=true, a tombstone. A source-restricted entry, active or deleted, is never exported, including for a person’s own MCP key. The export refuses files above 5,000 rows or 16 MiB with 413 payload_too_large, counting tombstones; it does not truncate them. Issued exports and refused exports are audited as the calling credential, with whether tombstones were asked for.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Query Parameters

scopeType
string
required

Knowledge scope type. A namespace outside the caller's readable set answers 403.

scopeId
string

Required for every scope except company and global, where it is forbidden.

Minimum string length: 1
includeDeleted
enum<string>
default:false

true to follow the active entries with deleted entries' tombstones (metadata only); default false.

Available options:
true,
false

Response

Time-limited NDJSON download URL

data
object
required
meta
object
required