Files

Files give agents durable knowledge and working context. Upload files when customers, projects, tasks, teams, or agents need searchable or downloadable artifacts, then index them so search.search() and search.references() can find them.

Quick Links

Action	Description
`files.list()`	List visible files.
`files.createUploadUrl()`	Create a signed upload URL.
`http.put('/files/upload/{path}')`	Upload raw file bytes through the API.
`files.finalize()`	Finalize a signed upload.
`files.get()`	Read file metadata.
`files.update()`	Update file metadata.
`files.delete()`	Delete a file.
`files.readContent()`	Read text content when available.
`files.createDownloadUrl()`	Create a signed download URL.
`files.index()`	Index a file for search.
`files.deleteIndex()`	Remove a file from the search index.
`files.summarize()`	Summarize a file.
`search.search()`	Search indexed file content.
`search.references()`	Find exact references and snippets.

Scopes And Areas

Every file lives at a scope + area + path address:

Scope — who the file belongs to: org, user, team, project, agent, or task. Every scope except org also needs a scopeId (the agent id, task id, and so on).
Area — what the file is for: input, notes, shared, brain, email, work, or output. For example, task inputs go in input, agent knowledge in brain (with a brainSnapshotId), and workspace-wide documents in shared.

Common Flow

Uploads are a three-step flow: create a signed upload URL, PUT the bytes to that URL, then finalize the file. The PUT goes directly to storage — it is plain HTTP with the returned uploadHeaders, not a Skopik API call, so it takes no Authorization header.

const { file, uploadUrl, uploadHeaders } = await client.files.createUploadUrl({
	scope: 'org',
	area: 'shared',
	path: 'policies/refund-policy.md',
	contentType: 'text/markdown',
})

await fetch(uploadUrl, { method: 'PUT', headers: uploadHeaders, body: policyMarkdown })

await client.files.finalize(file.fileRefId, { sizeBytes: 18432 })

import requests

upload = client.files.create_upload_url(
    scope="org",
    area="shared",
    path="policies/refund-policy.md",
    content_type="text/markdown",
)

requests.put(upload.upload_url, headers=upload.upload_headers, data=policy_markdown)

client.files.finalize(upload.file.file_ref_id, size_bytes=18432)

curl "$SKOPIK_API_BASE/files/upload_url" \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "org",
    "area": "shared",
    "path": "policies/refund-policy.md",
    "content_type": "text/markdown"
  }'

curl "$UPLOAD_URL" \
  -X PUT \
  -H "Content-Type: text/markdown" \
  --data-binary @refund-policy.md

curl "$SKOPIK_API_BASE/files/$FILE_REF_ID/finalize" \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "size_bytes": 18432
  }'

Then index the file and search it:

await client.files.index(file.fileRefId)

const { results } = await client.search.search({
	query: 'refund window for annual plans',
	mode: 'hybrid',
	limit: 5,
})

client.files.index(upload.file.file_ref_id)

results = client.search.search(
    query="refund window for annual plans",
    mode="hybrid",
    limit=5,
).results

curl "$SKOPIK_API_BASE/files/$FILE_REF_ID/index" \
  -X POST \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

curl "$SKOPIK_API_BASE/search" \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "refund window for annual plans",
    "mode": "hybrid",
    "limit": 5
  }'

Reference

`files.list(params?)`

List files visible to the current workspace.

const { data: files } = await client.files.list({ scope: 'org', area: 'shared' })

files = client.files.list(scope="org", area="shared").data

curl "$SKOPIK_API_BASE/files?scope=org&area=shared" \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Parameters

Field	Type	Required	Notes
`scope`	string	No	`org`, `user`, `team`, `project`, `agent`, or `task`.
`scopeId`	string	No	Required by scoped file sets other than `org`.
`area`	string	No	`input`, `notes`, `shared`, `brain`, `email`, `work`, or `output`.
`indexStatus`	string	No	Filter by index status.
`limit`	number	No	Page size.
`cursor`	string	No	Cursor from the previous page.

Returns ListResponse<FileRef> — { data: FileRef[], page? }. See FileRef.

`files.createUploadUrl(input)`

Create a signed URL for direct upload. Upload the bytes to uploadUrl with uploadHeaders, then call files.finalize().

const { file, uploadUrl, uploadHeaders } = await client.files.createUploadUrl({
	scope: 'task',
	scopeId: task.taskId,
	area: 'input',
	path: 'briefs/q3-pricing-brief.pdf',
	contentType: 'application/pdf',
})

upload = client.files.create_upload_url(
    scope="task",
    scope_id=task.task_id,
    area="input",
    path="briefs/q3-pricing-brief.pdf",
    content_type="application/pdf",
)

curl "$SKOPIK_API_BASE/files/upload_url" \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"scope\": \"task\",
    \"scope_id\": \"$TASK_ID\",
    \"area\": \"input\",
    \"path\": \"briefs/q3-pricing-brief.pdf\",
    \"content_type\": \"application/pdf\"
  }"

Parameters

Field	Type	Required	Notes
`scope`	string	Yes	`org`, `user`, `team`, `project`, `agent`, or `task`.
`area`	string	Yes	`input`, `notes`, `shared`, `brain`, `email`, `work`, or `output`.
`path`	string	Yes	Relative path inside the scope.
`scopeId`	string	No	Required unless `scope` is `org`.
`brainSnapshotId`	string	No	Brain snapshot id for brain files.
`name`	string	No	Display name. Defaults to the file name.
`contentType`	string	No	MIME type.
`sizeBytes`	number	No	Expected upload size.
`metadata`	object	No	Customer metadata.

Returns FileUploadUrl — { file, uploadUrl, uploadHeaders, expiresAt }.

`http.put('/files/upload/{path}')`

Upload raw file bytes through the API in a single call. There is no dedicated SDK method for this route — use the HTTP escape hatch. Prefer the signed-URL flow for large files; this route buffers the bytes through the API. client.http converts camelCase query keys to snake_case on the wire and the response back to camelCase.

const { file } = await client.http.put<{ file: FileRef }>(
	'/files/upload/policies/refund-policy.md',
	{
		query: { scope: 'org', area: 'shared' },
		headers: { 'Content-Type': 'text/markdown' },
		body: new Blob([policyMarkdown], { type: 'text/markdown' }),
	},
)

file = client.http.put(
    "/files/upload/policies/refund-policy.md",
    query={"scope": "org", "area": "shared"},
    headers={"Content-Type": "text/markdown"},
    body=policy_bytes,
).file

curl "$SKOPIK_API_BASE/files/upload/policies/refund-policy.md?scope=org&area=shared" \
  -X PUT \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: text/markdown" \
  --data-binary @refund-policy.md

Parameters

Field	Type	Required	Notes
`path`	string	Yes	Relative upload path, in the URL.
`scope`	string	Yes	Query param. `org`, `user`, `team`, `project`, `agent`, or `task`.
`scopeId`	string	No	Query param. Required unless `scope` is `org`.
`area`	string	Yes	Query param. File area.
`name`	string	No	Query param. Display name.
`brainSnapshotId`	string	No	Query param. Brain snapshot id for brain files.
`metadata`	string	No	Query param. Customer metadata encoded as JSON.
body	bytes	Yes	Raw file content, with its MIME type in the `Content-Type` header.

Returns { file: FileRef } — see FileRef.

`files.finalize(fileRefId, input?)`

Finalize a signed upload after the file bytes have been uploaded.

const { file: finalized } = await client.files.finalize(file.fileRefId, { sizeBytes: 18432 })

finalized = client.files.finalize(file_ref_id, size_bytes=18432).file

curl "$SKOPIK_API_BASE/files/$FILE_REF_ID/finalize" \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "size_bytes": 18432
  }'

Parameters

Field	Type	Required	Notes
`s3VersionId`	string	No	Storage version id when available.
`sizeBytes`	number	No	Final file size.
`checksum`	string	No	Checksum.
`mimeType`	string	No	MIME type.

Returns { file: FileRef } — see FileRef.

`files.get(fileRefId)`

Read file metadata.

const { file } = await client.files.get(fileRefId)

file = client.files.get(file_ref_id).file

curl "$SKOPIK_API_BASE/files/$FILE_REF_ID" \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Returns { file: FileRef } — see FileRef.

`files.update(fileRefId, input)`

Update file metadata.

const { file } = await client.files.update(fileRefId, {
	name: 'Refund policy (2026)',
	metadata: { reviewed: true },
})

file = client.files.update(
    file_ref_id,
    name="Refund policy (2026)",
    metadata={"reviewed": True},
).file

curl "$SKOPIK_API_BASE/files/$FILE_REF_ID" \
  -X PATCH \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Refund policy (2026)",
    "metadata": { "reviewed": true }
  }'

Parameters

Field	Type	Required	Notes
`name`	string	No	Display name.
`mimeType`	string	No	MIME type.
`sizeBytes`	number	No	File size.
`checksum`	string	No	Checksum.
`metadata`	object	No	Replacement metadata.

Returns { file: FileRef } — see FileRef.

`files.delete(fileRefId)`

Delete a file and its metadata.

await client.files.delete(fileRefId)

client.files.delete(file_ref_id)

curl "$SKOPIK_API_BASE/files/$FILE_REF_ID" \
  -X DELETE \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Returns nothing — resolves when the API confirms deletion (HTTP 204).

`files.readContent(fileRefId)`

Read extracted text content when available.

const { content, sizeBytes } = await client.files.readContent(fileRefId)

content = client.files.read_content(file_ref_id).content

curl "$SKOPIK_API_BASE/files/$FILE_REF_ID/content" \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Returns { file: FileRef, content: string, sizeBytes: number } — see FileRef.

`files.createDownloadUrl(fileRefId)`

Create a signed download URL.

const { downloadUrl, expiresAt } = await client.files.createDownloadUrl(fileRefId)

download = client.files.create_download_url(file_ref_id)
print(download.download_url)

curl "$SKOPIK_API_BASE/files/$FILE_REF_ID/download_url" \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Returns FileDownloadUrl.

`files.index(fileRefId, input?)`

Request indexing for a file so search.search() can find its content.

const { file } = await client.files.index(fileRefId)

file = client.files.index(file_ref_id).file

curl "$SKOPIK_API_BASE/files/$FILE_REF_ID/index" \
  -X POST \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Parameters

Field	Type	Required	Notes
`jobId`	string	No	Optional caller-provided job id.

Returns { file: FileRef } — see FileRef.

`files.deleteIndex(fileRefId)`

Remove search index state for a file. The file itself is untouched.

const { file } = await client.files.deleteIndex(fileRefId)

file = client.files.delete_index(file_ref_id).file

curl "$SKOPIK_API_BASE/files/$FILE_REF_ID/index" \
  -X DELETE \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Returns { file: FileRef } — see FileRef.

`files.summarize(fileRefId, input?)`

Generate a summary for a file.

const summary = await client.files.summarize(fileRefId, {
	instructions: 'Focus on refund windows and exceptions.',
})
console.log(summary.summary)

summary = client.files.summarize(
    file_ref_id,
    instructions="Focus on refund windows and exceptions.",
)
print(summary.summary)

curl "$SKOPIK_API_BASE/files/$FILE_REF_ID/summary" \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Focus on refund windows and exceptions."
  }'

Parameters

Field	Type	Required	Notes
`instructions`	string	No	Summary instructions.
`maxOutputTokens`	number	No	Output token cap.

Returns DocumentSummary.

`search.search(input)`

Search indexed file content.

const { results } = await client.search.search({
	query: 'refund window for annual plans',
	mode: 'hybrid',
	filters: { scope: 'org', area: 'shared' },
	limit: 5,
})

results = client.search.search(
    query="refund window for annual plans",
    mode="hybrid",
    filters={"scope": "org", "area": "shared"},
    limit=5,
).results

curl "$SKOPIK_API_BASE/search" \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "refund window for annual plans",
    "mode": "hybrid",
    "filters": { "scope": "org", "area": "shared" },
    "limit": 5
  }'

Parameters

Field	Type	Required	Notes
`query`	string	Yes	Search query.
`mode`	string	No	`hybrid`, `vector`, or `lexical`.
`filters`	SearchFilters	No	Scope, area, path, kind, or agent filters. See `SearchFilters`.
`limit`	number	No	Maximum results.

Returns SearchResponse.

`search.references(input)`

Find exact references and snippets — the literal string, not semantic matches.

const { hits } = await client.search.references({
	query: 'INV-2026-0142',
	mode: 'indexed',
	wholeWord: true,
})

hits = client.search.references(
    query="INV-2026-0142",
    mode="indexed",
    whole_word=True,
).hits

curl "$SKOPIK_API_BASE/search/references" \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "INV-2026-0142",
    "mode": "indexed",
    "whole_word": true
  }'

Parameters

Field	Type	Required	Notes
`query`	string	Yes	Text or reference to find.
`mode`	string	No	`indexed` or `exhaustive`.
`caseSensitive`	boolean	No	Match case exactly.
`wholeWord`	boolean	No	Match whole words only.
`filters`	SearchFilters	No	Scope, area, path, kind, or agent filters. See `SearchFilters`.
`fileRefIds`	string[]	No	Limit search to specific files.
`limit`	number	No	Maximum hits.

Returns ReferenceSearchResponse.

Types

`FileRef`

Field	Type	Notes
`fileRefId`	string	File reference id.
`orgId`	string	Workspace id.
`scope`	string	File scope.
`scopeId`	string	Scope id when the scope is not workspace-wide.
`area`	string	File area.
`brainSnapshotId`	string	Brain snapshot id when present.
`name`	string	Display name.
`path`	string	Storage path.
`pathHash`	string	Stable path hash.
`s3Bucket`	string	Storage bucket.
`s3Key`	string	Storage object key.
`s3VersionId`	string	Storage version id.
`finalizedAt`	string	ISO timestamp when finalized.
`mimeType`	string	MIME type.
`sizeBytes`	number	File size.
`source`	string	Source, such as `upload`.
`checksum`	string	Checksum.
`createdBy`	string	Creator id.
`index`	object	Index state. Defaults to `{ "status": "unindexed" }`.
`metadata`	object	Customer metadata.
`createdAt`	string	ISO timestamp.
`updatedAt`	string	ISO timestamp.

`FileUploadUrl`

Field	Type	Notes
`file`	FileRef	File metadata. See `FileRef`.
`uploadUrl`	string	Signed upload URL.
`uploadHeaders`	object	Headers to include with the upload.
`expiresAt`	string	ISO timestamp when the URL expires.

`FileDownloadUrl`

Field	Type	Notes
`downloadUrl`	string	Signed download URL.
`expiresAt`	string	ISO timestamp when the URL expires.
`s3Bucket`	string	Storage bucket.
`s3Key`	string	Storage object key.

`DocumentSummary`

Field	Type	Notes
`fileRefId`	string	File reference id.
`path`	string	File path.
`summary`	string	Generated summary.
`model`	string	Model used for the summary.
`coverage`	object	Document coverage and warnings.
`usage`	object	Input and output token counts.
`diagnostics`	object	Latency and call-count diagnostics.

`SearchFilters`

Field	Type	Notes
`scope`	string	File scope.
`scopeId`	string	Scope id.
`area`	string or string[]	File area filter.
`brainSnapshotId`	string	Brain snapshot id.
`pathPrefix`	string	Path prefix.
`kinds`	string[]	Content kind filter.
`agentId`	string	Agent id.

`SearchResponse`

Field	Type	Notes
`results`	SearchResultHit[]	Ranked results. See `SearchResultHit`.
`diagnostics`	object	Mode, chunk count, and latency.

`SearchResultHit`

Field	Type	Notes
`chunkId`	string	Matching chunk id.
`score`	number	Relevance score.
`scope`	string	File scope.
`scopeId`	string	Scope id.
`area`	string	File area.
`sourceFileRefId`	string	Source file reference id.
`path`	string	Source path.
`text`	string	Matching text.
`page`	number	Page number when available.
`byteOffset`	number	Byte offset when available.
`mimeType`	string	MIME type.
`headingPath`	string[]	Heading hierarchy.
`documentVersion`	string	Indexed document version.

`ReferenceSearchResponse`

Field	Type	Notes
`query`	string	Search query.
`mode`	string	Search mode used.
`hits`	ReferenceHit[]	Matching references. See `ReferenceHit`.
`coverage`	object	Scan coverage and warnings.
`diagnostics`	object	Latency and candidate count.

`ReferenceHit`

Field	Type	Notes
`fileRefId`	string	File reference id.
`path`	string	Source path.
`documentVersion`	string	Indexed document version.
`blockId`	string	Matching block id.
`blockKind`	string	Block kind.
`page`	number	Page number when available.
`headingPath`	string[]	Heading hierarchy.
`matchStart`	number	Match start offset.
`matchEnd`	number	Match end offset.
`blockCharStart`	number	Block start offset.
`blockCharEnd`	number	Block end offset.
`snippet`	string	Snippet around the match.