takibibase.com Paid content

OpenAPI-generated API documentation is reference documentation that is produced automatically from an OpenAPI description file rather than written by hand. You write (or generate) a machine-readable specification of your API — endpoints, parameters, request bodies, responses, schemas, and auth — and a documentation tool reads that file and renders a browsable, often interactive reference site. The spec becomes the single source of truth; the docs become a build artifact.

This differs from manually written docs in one fundamental way: with hand-written docs, the prose is the source of truth and the API is described separately. With spec-driven docs, the API description is the source, and every page, table, and code sample is derived from it.

How the workflow actually runs

A typical spec-driven documentation pipeline has five stages:

1. Author or generate the spec. You either write an OpenAPI document by hand (YAML or JSON), or generate it from code annotations, framework metadata, or a design-first editor. Design-first means the spec is written before implementation; code-first means it is extracted from existing code.
2. Validate and lint. The spec is checked against the OpenAPI schema and against style rules — consistent naming, required descriptions, no undocumented 4xx responses, no orphaned schemas.
3. Bundle and transform. Multi-file specs are combined, $ref pointers are resolved, and the document is optionally split into per-tag or per-version outputs.
4. Render. A documentation tool converts the spec into HTML: an endpoint list, a sidebar of operations, parameter tables, response schemas, and a "try it" console.
5. Publish and version. The rendered site is deployed, and each API version gets its own snapshot so consumers can read docs matching the version they call.

Steps 2 through 5 are usually automated in CI. If the spec fails validation, the docs build fails — which is the point.

Spec-driven vs. hand-written documentation

The practical conclusion most teams reach: generate the reference, write the guides. Reference material is repetitive and mechanical, which is exactly what generation is good at. Conceptual explanations, migration notes, and tutorials carry judgment that a spec cannot express.

What you get out of the box

Generated reference pages commonly include:

• An operation list grouped by tag or path, with HTTP method and path.
• Parameter tables showing name, location (path, query, header, cookie), type, required flag, and description.
• Request and response schemas rendered as expandable trees, including nested objects and arrays.
• Authentication details pulled from the securitySchemes section.
• Interactive request consoles that let a reader send a real call from the browser.
• Generated code samples in several languages, derived from the same schemas.
• Multiple output formats, such as a static site, a single HTML file, or a mock server.

Because all of these come from one document, changing a field name in the spec updates the parameter table, the schema tree, and every code sample at once.

Where spec-driven documentation breaks down

Generation is not free. The trade-offs are real:

Spec quality becomes documentation quality. A field with no description produces a table row with an empty cell. A vague summary produces a vague heading. Tools can enforce presence of descriptions via linting, but they cannot enforce that the description is useful.

Customization has limits. If you need a page that does not map to an OpenAPI concept — a conceptual overview, a pricing explanation, a comparison of two endpoints — you write it outside the generator and link to it.

Not everything is expressible. Webhooks, streaming responses, long-polling behavior, and complex multi-step flows are awkward or impossible to describe fully in OpenAPI. Those need prose.

The spec can go stale. If the spec is maintained separately from the implementation, it drifts just like hand-written docs. The mitigation is to generate the spec from code, or to test the implementation against the spec in CI.

Interactive consoles need care. A "try it" button that hits a production API with real credentials is a security and rate-limit problem. Point it at a sandbox, or disable it.

Deciding whether to adopt it

Adopt spec-driven reference documentation if most of these are true:

• Your API has more than a handful of endpoints, or changes frequently.
• You ship client SDKs or code samples in more than one language.
• Multiple teams consume the API and need a consistent, always-current reference.
• You already have, or are willing to maintain, an OpenAPI description.

Stay with hand-written docs, or a hybrid, if:

• Your API is small and stable, and the reference fits on one page.
• Your documentation is mostly conceptual and contains little endpoint-level detail.
• You cannot commit to keeping the spec in sync with the implementation.

A reasonable middle path: generate the reference from the spec, and hand-write the getting-started guide, authentication walkthrough, and error-handling page. Link the two directions so readers can move from concept to endpoint and back.

A minimal starting checklist

1. Produce one valid OpenAPI document for a single API version.
2. Add a linter with rules for descriptions, operation IDs, and error responses.
3. Wire the docs build into CI so a failing spec fails the build.
4. Render the reference and review it as a reader, not as the author.
5. Write the two or three conceptual pages the generator cannot produce.
6. Version the published docs alongside the API version.

The core idea is simple: describe the API once, in a format both machines and humans can read, and let the reference documentation fall out of that description. Everything else — tooling, hosting, interactivity — is a detail on top of that decision.

Takibi Base offers a sample workspace you can explore without signing up for anything. You can browse how documents are organized, change Profile access settings, and run questions through the CLI against sample data. The catch: any edits you make in the demo reset when you refresh the page, and anything that touches real storage — uploads, imports, downloads, and billing — requires your own workspace.

What you can try in the sample workspace

The demo is built to let you see the core mechanics of Takibi Base before committing to a workspace. According to the site, you can:

• Browse document organization — see how files sit inside projects and folders, and how Takibi converts them to Markdown for agent search.
• Change Profile access — open a Profile's Access tab, choose Edit, and select which folders it can read. This is the same permission model you'd use in production.
• Ask a question via the CLI — run a query and see the response format: matching passages, citations, and an evidence support score.

The CLI example on the site shows what a real response looks like:

$ takibi ask -q "What is our refund policy?" --json
{
  "spans": [{
    "text": "Customers may request a refund within 30 days of purchase.",
    "documentId": "00000000-0000-4000-8000-000000000010",
    "documentName": "refunds.md",
    "chunkId": "00000000-0000-4000-8000-000000000090",
    "title": "Eligibility"
  }],
  "citations": [{ ... }],
  "support": 0.4,
  "supportVersion": "v1",
  "abstained": false,
  "candidateCount": 1,
  "answerability": "unknown",
  "conflict": false
}

Each returned span includes the exact passage text plus a citation (document ID, document name, chunk ID, title). The support field is a measure of how well the retrieved evidence backs the answer — in this example, 0.40 on version v1 of the scoring.

What resets when you refresh

The demo is explicitly non-persistent. The site states that demo changes reset when you refresh, and that edits reset on refresh. So you can experiment freely with:

• Changing folder access on a Profile
• Modifying document organization
• Running different CLI queries

None of it carries over. Treat the sample workspace as a sandbox for understanding the workflow, not as a place to set up real configuration.

What requires your own workspace

Four operations are gated behind a personal workspace, per the site:

If your goal is to test whether Takibi handles your actual document types, or to verify that your files convert correctly to Markdown, you'll need to create a workspace. The demo only shows the interface and query mechanics against sample data.

Checking plans and pricing

There's a pricing page at takibase.com/pricing for workspace plans. The site doesn't publish specific pricing details in the material available here, so check that page directly for current numbers. Billing is one of the operations that requires your own workspace, so you won't encounter payment flows in the demo.

A practical way to evaluate it

1. Start in the sample workspace. Run the CLI query example, change a Profile's folder access, and look at how documents are indexed (the site mentions statuses like indexed, converting, and quarantined).
2. Note what you'd need to test with real data. If your evaluation depends on uploading your own files or checking conversion quality, plan to create a workspace.
3. Check the pricing page before creating a workspace so you know what you're signing up for.
4. Export format — the site mentions exporting a project in Open Knowledge Format (OKF). If that matters to your workflow, verify it works in your own workspace, since exports likely fall under the download restriction.

The demo is enough to decide whether the Profile-based access model and cited-passage response format fit how you want your agents to retrieve information. It isn't enough to validate document conversion on your own corpus — that step needs a workspace.

Takibi Base answers an agent's question by searching the documents you've uploaded and returning the matching passages themselves — not a rewritten summary. Each passage comes with a citation (document ID, document name, chunk ID, and title) plus an evidence support score. If it finds no matching evidence, it returns no passages instead of guessing. This applies to questions asked through the CLI or API against documents in your own workspace.

What the agent actually receives

When a tool asks a question, Takibi searches the sources that the Profile's keys are allowed to read. The response is structured, so the calling agent can quote the source text and point back to where it came from.

From the documented CLI example:

$ takibi ask -q "What is our refund policy?" --json
{
  "spans": [{
    "text": "Customers may request a refund within 30 days of purchase.",
    "documentId": "00000000-0000-4000-8000-000000000010",
    "documentName": "refunds.md",
    "chunkId": "00000000-0000-4000-8000-000000000090",
    "title": "Eligibility"
  }],
  "citations": [{ ... }],
  "support": 0.4,
  "supportVersion": "v1",
  "abstained": false,
  "candidateCount": 1,
  "answerability": "unknown",
  "conflict": false
}

The key fields:

The evidence support score is described as "a measure of support in the retrieved evidence." In the sample, a single cited passage produced a support value of 0.40 — so a low score with one candidate is a signal to check the source rather than trust the answer outright.

Why passages instead of generated answers

Takibi's stated design is "The source. In its own words." The agent gets the source text and a citation for each passage, which means the grounding happens at the retrieval layer: the tool decides what to do with the passage, but it can always show where the text came from. This is what makes answers citable rather than paraphrased.

The flip side is the abstention behavior: if no matching evidence is found, Takibi returns no passages. There is no fallback to a generated guess, so an empty result is a meaningful signal that the documents don't cover the question.

What has to be in place first

Retrieval only works over documents that are indexed and permitted:

1. Upload documents into projects and folders. Takibi converts them to Markdown so agents can search them. You can download the originals or extract their text again.
2. Check indexing status. Files show as indexed, converting, or quarantined. Only indexed content is searchable.
3. Grant access through a Profile. A Profile holds a tool's keys and document permissions. Open the Profile's Access tab, choose Edit, and select the folders it can read. Every key in that Profile uses those permissions.
4. Account for future content. Folder access includes documents you add later, once they are indexed. Project access also includes future folders and documents outside folders — Takibi asks you to confirm this broader access.

Separate Profiles are the intended way to give different tools different access, so a tool that only needs refund policy documents doesn't search everything.

Common points to watch

• Uploads, imports, downloads, and billing require your own workspace. The sample workspace is for trying things out, and edits reset on refresh — so demo results won't persist.
• A folder grant is not retroactive to unindexed files. New documents become readable only after indexing completes.
• A low support score with few candidates is worth inspecting. The response exposes candidateCount and conflict precisely so the calling agent can decide whether to rely on the passage.
• Project-level access is broader than it looks. It reaches future folders and documents outside folders, which is why Takibi requires explicit confirmation.

To see the retrieval behavior before wiring anything up, the sample workspace lets you ask questions and change access, with the caveat that changes reset on refresh.

A Profile in Takibi Base bundles a tool's API keys with its document permissions, so every key in that Profile reads exactly the folders you assign to it. To scope access, create a separate Profile for each tool that needs different reach, then open its Access tab, choose Edit, and select the folders it should read. Folder access automatically extends to documents you add later once they are indexed; project-level access is broader and Takibi asks you to confirm it.

What a Profile actually holds

A Profile is the unit that ties two things together:

• Keys — the credentials a tool uses to call Takibi.
• Document permissions — the folders those keys are allowed to read.

Because permissions live on the Profile rather than on individual keys, every key inside a Profile inherits the same access. That is why the recommended pattern is one Profile per tool with a distinct access need, instead of one shared Profile for everything.

Setting folder access step by step

1. Create a Profile for the tool you are connecting.
2. Open the Profile's Access tab and choose Edit.
3. Select the folders the Profile should be able to read.
4. Confirm if you are granting project-level access, which is wider than folder access.

Expected result: when that tool asks a question through the CLI or API, Takibi searches only the sources the Profile can read.

Folder access vs. project access

The distinction matters because folder access is forward-looking within a folder, while project access reaches beyond any single folder. If a tool should never see a new folder you create later, keep it on folder access.

What the agent gets back

When a tool asks a question, Takibi returns matching passages, citations, and an evidence support score. A CLI call looks like this:

$ takibi ask -q "What is our refund policy?" --json

The response includes spans with the exact passage text, a documentId, documentName, chunkId, and title, plus a citations array and a support score (for example 0.4, with supportVersion: "v1"). If no matching evidence is found, Takibi returns no passages — the agent gets source text and a citation for each passage rather than an unsourced answer.

Common sticking points

• New documents aren't searchable immediately. Folder access includes documents you add later once they are indexed. Check whether a file is indexed, converting, or quarantined before assuming access is broken.
• Permissions are per Profile, not per key. If two tools need different access, splitting keys inside one Profile won't work — create separate Profiles.
• Project access is easy to grant by accident. It covers future folders and documents outside folders, so confirm deliberately.
• Demo changes don't persist. Sample workspace edits reset on refresh, and uploads, imports, downloads, and billing require your own workspace.

Takibi Base is a shared knowledge base for AI agents. You upload documents into projects and folders, and agents query them through a CLI or API to get back exact cited passages rather than generated summaries. It fits teams that need agents to answer from their own documents with verifiable sources, and that want to scope what each tool can read.

How it works

The core idea is that your agent doesn't get your whole document set. It gets passages that match a question, plus a citation for each one.

1. Add documents — upload files into projects and folders. Takibi converts them to Markdown so agents can search them.
2. Choose access — a Profile holds a tool's keys and document permissions. You select which folders that Profile can read.
3. Ask questions — the tool queries through the CLI or API. Takibi searches only those sources and returns matching passages with citations.

You can also download the original files or extract their text again, and check which files are indexed, converting, or quarantined. Projects can be exported in Open Knowledge Format (OKF).

What a response looks like

A CLI query returns structured output, not prose. From the sample workspace:

$ takibi ask -q "What is our refund policy?" --json

The response includes:

In the example, the passage returned is: "Customers may request a refund within 30 days of purchase." — attributed to refunds.md, section "Eligibility". The agent gets the source text and a citation for each passage.

If Takibi finds no matching evidence, it returns no passages. That abstention behavior matters if you're building agents that shouldn't guess.

Access control through Profiles

A Profile holds the access permissions for its keys. Every key in a Profile uses the same permissions, so create separate Profiles for tools that need different access.

To scope a Profile:

1. Open the Profile's Access tab and choose Edit.
2. Select the folders it should be able to read.

Two scope levels behave differently:

• Folder access includes documents you add later, once they are indexed.
• Project access also includes future folders and documents outside folders. Takibi asks you to confirm this broader access.

What to check before committing

• Workspace requirement. Uploads, imports, downloads, and billing require your own workspace. The sample workspace is for trying things out — edits reset on refresh.
• Pricing. A pricing page exists at takibibase.com/pricing, but the available material doesn't state amounts or plan details, so check it directly.
• Fit. If your agents need to cite exact passages from your own documents and you want per-tool read scoping, this matches that need. If you need agents to synthesize across sources rather than return evidence, the passage-and-citation model is a different shape.