Developer OpenAPI

Developer OpenAPI gives applications programmatic access to Focowiki. A product can create knowledge bases, upload Markdown files and folders, observe processing, read files, explore relationships, manage uploaded content, and receive Webhook events.

Connection

Use the Developer OpenAPI origin configured for your deployment. All API paths start with /openapi/v2.

https://openapi.example.com

Local development commonly uses http://127.0.0.1:43200.

Every request requires an OpenAPI key created in Admin UI:

Authorization: Bearer <openapi-key>

The running service publishes its machine-readable contract at:

GET /openapi/v2/openapi.json

The documentation site also provides a contract snapshot for the documented release. Use the runtime contract when generating a client for a specific deployment.

Use the API Explorer to filter operations, inspect examples, and review schemas from the same release contract in a read-only interface.

Response Conventions

Successful list responses contain items and nextCursor. Pass nextCursor back to the same endpoint with the same filters to read the next page.

Errors use the same JSON structure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request failed validation.",
    "httpStatus": 422
  },
  "requestId": "req-11111111-1111-4111-8111-111111111111"
}

All operations can return 401 UNAUTHORIZED, 429 RATE_LIMITED, 500 INTERNAL_ERROR, or 503 DATABASE_REPOSITORY_UNAVAILABLE. A rate-limited response includes retry guidance. Clients should wait for the suggested interval and retry the current operation.

Resource Identifiers

Identifiers have distinct purposes and remain stable across related calls.

A source file is the original Markdown file accepted by an upload or replacement request. The API uses sourceFileId for this uploaded file. A source directory is a folder preserved from the uploaded file path. A generated file is the current readable knowledge-base file produced from uploaded content or navigation data. activeContentRevision is the numeric revision of the current readable knowledge-base content; a knowledge base with no readable content reports 0, while nullable read responses use null.

Identifier	Obtained from	Used for
knowledgeBaseId	Knowledge-base create or list responses	Scope every knowledge-base operation.
uploadSessionId	Upload-session create response	Resume, inspect, cancel, or complete an upload.
sourceFileId	Upload and uploaded-file responses	Read upload and processing status or content, retry, move, replace, and delete.
directoryId	Uploaded-directory and tree responses	Read, move, or delete an uploaded directory.
operationId	Upload-session and resource-change responses	Check progressive upload indexing or the result of a resource change.
fileId	Tree, search, related-file, and file responses	Read current file metadata, content, and relationships.
path	Tree, search, links, and file responses	Read a current file by its knowledge-base path.

Storage paths and local filesystem paths are not accepted.

Upload Workflow

Uploads preserve relative folder paths. Every uploaded item must be a Markdown file.

Before finalizing an upload, configure one active generation model and one active validated Embedding configuration in Admin. Finalization rejects an unconfigured knowledge base before creating document jobs; uploaded transfer data remains available so the configuration can be corrected and finalization retried.

1. Create a knowledge base and keep its knowledgeBaseId.
2. Create an upload session with the declared file and byte counts.
3. Add each file's relative path and size to the upload file list. This list is named the upload manifest in API paths and schema names. A SHA-256 checksum can be included to verify the uploaded content.
4. Confirm that the upload file list is complete.
5. Upload content for entries whose disposition is upload_required.
6. Complete the upload session and retain its operationId or actions.operation link.
7. Poll the operation for progressive document counts. Each document with state available is immediately readable and searchable while sibling documents may still be processing.
8. Use each file's sourceFileId to read its current status and content.

Upload registration has no product-level file-count or byte quota. The session response states how many file records can be added in one request. Upload each required Markdown body through the entry ID returned by the session. Reusing an existing folder path adds new files. Existing files at the same relative path are skipped. Use the uploaded-file replacement operation when content at an existing path must change.

Minimal Example

The example uploads guide.md as handbook/onboarding/guide.md. It uses jq, wc, and shasum to pass values between requests.

OPENAPI_BASE_URL="https://openapi.example.com"
OPENAPI_KEY="<openapi-key>"
FILE_PATH="guide.md"
RELATIVE_PATH="handbook/onboarding/guide.md"

kb=$(curl -sS -X POST "$OPENAPI_BASE_URL/openapi/v2/knowledge-bases" \
  -H "Authorization: Bearer $OPENAPI_KEY" \
  -H "Content-Type: application/json" \
  --data '{"name":"Product Docs","description":"Product documentation"}')
KNOWLEDGE_BASE_ID=$(printf '%s' "$kb" | jq -r '.knowledgeBase.knowledgeBaseId')

FILE_SIZE=$(wc -c < "$FILE_PATH" | tr -d ' ')
FILE_SHA256=$(shasum -a 256 "$FILE_PATH" | awk '{print $1}')

session=$(curl -sS -X POST "$OPENAPI_BASE_URL/openapi/v2/knowledge-bases/$KNOWLEDGE_BASE_ID/upload-sessions" \
  -H "Authorization: Bearer $OPENAPI_KEY" \
  -H "Idempotency-Key: product-docs-upload-001" \
  -H "Content-Type: application/json" \
  --data "{\"declaredFileCount\":1,\"declaredByteCount\":$FILE_SIZE}")
UPLOAD_SESSION_ID=$(printf '%s' "$session" | jq -r '.session.id')

manifest=$(jq -n --arg path "$RELATIVE_PATH" --arg checksum "$FILE_SHA256" \
  --argjson size "$FILE_SIZE" \
  '{entries:[{relativePath:$path,declaredSize:$size,checksumSha256:$checksum}]}')

curl -sS -X POST "$OPENAPI_BASE_URL/openapi/v2/knowledge-bases/$KNOWLEDGE_BASE_ID/upload-sessions/$UPLOAD_SESSION_ID/entries" \
  -H "Authorization: Bearer $OPENAPI_KEY" \
  -H "Content-Type: application/json" \
  --data "$manifest"

curl -sS -X POST "$OPENAPI_BASE_URL/openapi/v2/knowledge-bases/$KNOWLEDGE_BASE_ID/upload-sessions/$UPLOAD_SESSION_ID/seal" \
  -H "Authorization: Bearer $OPENAPI_KEY"

status=$(curl -sS "$OPENAPI_BASE_URL/openapi/v2/knowledge-bases/$KNOWLEDGE_BASE_ID/upload-sessions/$UPLOAD_SESSION_ID?limit=50" \
  -H "Authorization: Bearer $OPENAPI_KEY")
UPLOAD_ENTRY_ID=$(printf '%s' "$status" | jq -r '.entries.items[] | select(.disposition == "upload_required") | .id' | head -n 1)

uploaded=$(curl -sS -X PUT "$OPENAPI_BASE_URL/openapi/v2/knowledge-bases/$KNOWLEDGE_BASE_ID/upload-sessions/$UPLOAD_SESSION_ID/entries/$UPLOAD_ENTRY_ID/content" \
  -H "Authorization: Bearer $OPENAPI_KEY" \
  -H "Content-Type: text/markdown" \
  --data-binary "@$FILE_PATH")
SOURCE_FILE_ID=$(printf '%s' "$uploaded" | jq -r '.entry.sourceFileId')

curl -sS -X POST "$OPENAPI_BASE_URL/openapi/v2/knowledge-bases/$KNOWLEDGE_BASE_ID/upload-sessions/$UPLOAD_SESSION_ID/finalize" \
  -H "Authorization: Bearer $OPENAPI_KEY"

Processing State

Use the uploaded-file detail operation to determine when content is ready.

Field	Values	Meaning
state	waiting, processing, available, error, deleting	Overall document-indexing status of the uploaded file.
workProgress	object	Progress across the required document work. activeKinds lists work in progress; blockingKind and retryingKind identify work that is waiting or will be retried.
failure	object or null	Error details and the available retry type.
generatedOutputStatus	unavailable, previous_available, current_available	Whether no generated content, the previous active revision, or the current revision can be read.
actions	array	API calls currently available for this file.

A file is ready when state is available. Use state as the availability authority; workProgress can still show final cleanup after the file becomes available. When state is error, read failure.workKind and follow one of the returned actions. A failed replacement may keep its previous readable content, while a failed first upload is not exposed through content, tree, graph, or search reads.

curl -sS "$OPENAPI_BASE_URL/openapi/v2/knowledge-bases/$KNOWLEDGE_BASE_ID/source-files/$SOURCE_FILE_ID" \
  -H "Authorization: Bearer $OPENAPI_KEY"

File Reading And Exploration

Start with index.md, inspect the tree, and read matching files before using them as evidence.

curl -sS -G "$OPENAPI_BASE_URL/openapi/v2/knowledge-bases/$KNOWLEDGE_BASE_ID/files/content" \
  -H "Authorization: Bearer $OPENAPI_KEY" \
  --data-urlencode "path=index.md"

Nested upload paths are generated under pages/. The uploaded example can be read at pages/handbook/onboarding/guide.md after it becomes available:

curl -sS -G "$OPENAPI_BASE_URL/openapi/v2/knowledge-bases/$KNOWLEDGE_BASE_ID/files/content" \
  -H "Authorization: Bearer $OPENAPI_KEY" \
  --data-urlencode "path=pages/handbook/onboarding/guide.md"

The tree endpoint supports parent-path navigation, fuzzy lookup, type filtering, and cursor pagination. Search accepts one standalone natural-language question from 2 through 512 grapheme clusters and at most 2048 UTF-8 bytes after normalization. Unsafe control characters are rejected. Send the complete question without local decomposition. Omit mode to use the recommended hybrid retrieval. file searches file paths, titles, metadata, content, and semantic similarity. graph follows file relationships and graph-derived semantic signals. hybrid combines both. Use scope=path for paths and titles, scope=metadata for metadata, or scope=all for the complete search scope.

Search returns active Markdown pages created from uploaded files. fileKind=page is the default; fileKind=all removes the explicit type predicate but currently returns the same page set. OKF filters are optional and exclude files without matching valid OKF signals, so omit them for unrestricted search. graphDepth=0 returns only the seed graph reference, 1 includes direct relationships, and 2 may include second-level relationships within the requested graphFanout. Search results include fileId, path, actual matched fields, safe evidence types, a short source excerpt when available, status, and read actions.

Search and relationship results guide navigation. Applications should read the returned Markdown files before presenting an answer.

curl -sS -G "$OPENAPI_BASE_URL/openapi/v2/knowledge-bases/$KNOWLEDGE_BASE_ID/files/search" \
  -H "Authorization: Bearer $OPENAPI_KEY" \
  --data-urlencode "query=How do I install, configure, and verify this knowledge base?" \
  --data-urlencode "mode=hybrid" \
  --data-urlencode "limit=10"

Search returns searchStatus=ok or searchStatus=no_candidates. no_candidates describes only the current query result and does not prove that the knowledge base lacks relevant content. Dependency failures use the documented 503 or 504 error envelope. The response exposes stable semantic and reranker reason codes plus the completed and degraded evidence-family enums. A 422 response uses top-level VALIDATION_ERROR; its details.code is one of the operation's machine-readable x-validation-detail-codes, such as FILE_SEARCH_QUERY_TOO_LONG, INVALID_FILE_SEARCH_KIND, or INVALID_FILE_SEARCH_RERANK_CONTROLS.

Reranking is disabled by default. Set rerank=true per request to use the active Admin-configured reranker; rerankTopK controls its non-exact candidate window and rerankScoreThreshold filters only valid non-exact reranker scores. The threshold defaults to 0, making reranking reorder-only. An explicitly positive threshold can return RERANKER_ALL_BELOW_THRESHOLD when it removes every non-exact candidate. Missing or failed reranking falls back to deterministic hybrid order and reports a safe rerankerStatus. Search excerpts, entity or relationship labels, community summaries, and reranker output are discovery hints. Read the returned source Markdown through readActions before using its content in an answer.

Manage Uploaded Content

Uploaded files support content reads, moves, full-content replacement, retry, and deletion. Uploaded directories support listing, moves, and recursive deletion. Upload sessions and resource changes return an operationId; use the operation endpoints to check progressive indexing, change progress, and results.

Deleting an uploaded file removes its current generated page and relationships. Deleting an uploaded directory removes all uploaded files below it. Deleting a knowledge base starts deletion for the complete knowledge base and makes it unavailable to later reads.

Webhooks

Webhook subscriptions deliver uploaded-file and knowledge-base update events to an HTTPS endpoint. See Webhook Delivery for event names, signature verification, payloads, delivery records, and manual redelivery.

Agent Integration

Keep the OpenAPI key in an application backend. Give the Agent a small read interface that can list the tree, read files, search for matching files, and follow relationships. See Agent Integration for integration patterns and Skill guidance.

Interface Reference

The Operation Index contains one generated page for every operationId, including parameters, request bodies, examples, responses, and operation-specific errors.