Inkpilots

Integrations and API

Operations

Inkpilots includes API and integration surfaces for teams that want to read workspace data programmatically, build external experiences, or connect the platform to other operational systems. These capabilities should be treated as an extension of the workspace, not as a separate product.

This page explains what the current integration layer actually exposes and how to govern it responsibly.

What this area is for

Use integrations and API features when your team needs to:

  • create API keys for programmatic access,
  • expose workspace or published content to external systems,
  • build custom frontends on top of the content model,
  • inspect usage caused by API traffic,
  • separate editorial operations from downstream delivery surfaces.

The key point is that API access changes how the workspace can be consumed and controlled. It should be introduced deliberately.

API keys in the current product

Inkpilots currently provides a dedicated API keys tab at the workspace level. The current API key workflow supports:

  • listing existing keys,
  • creating a named API key,
  • revealing the secret only at creation time,
  • copying the new key immediately,
  • deleting keys that should no longer exist,
  • viewing creation date and last-used information when available.

This means API access is governed through explicit credentials, not through informal reuse of dashboard access.

Why API key handling matters

The product only shows a newly created key once. That is a deliberate security choice. Teams should treat that moment as a credential handoff, not as a temporary convenience.

Good practice includes:

  • naming keys clearly,
  • storing them safely outside the dashboard,
  • deleting keys that are no longer needed,
  • avoiding shared anonymous keys for unrelated consumers.

The current V1 API surface

The repository currently exposes a V1 API layer under /api/v1. The available documented endpoint groups include:

  • articles,
  • agents,
  • workspaces.

The current V1 documentation describes endpoints such as:

  • listing articles,
  • fetching one article,
  • listing agents,
  • fetching one agent,
  • fetching articles for a specific agent,
  • fetching a workspace snapshot that includes workspace metadata, agents, and published articles.

These endpoints are enough to support custom read-driven experiences on top of Inkpilots-managed content.

What the V1 API is useful for

The current V1 design is especially useful when teams want to:

  • build a custom public frontend,
  • render published content outside the default public workspace,
  • create “desk” or agent-based views of content,
  • power search and list pages from external applications,
  • read workspace metadata and published article structures programmatically.

In other words, the API is already useful for delivery and presentation use cases even when the built-in public workspace is not the final destination.

Authentication model

The V1 API documentation expects requests to be authenticated with an API key header.

That means programmatic consumers should be treated as privileged clients. Once a key exists, the external system effectively becomes a participant in the workspace’s operating perimeter.

Integration usage is still usage

API activity is not operationally invisible. The current workspace usage view already records API-related usage reasons, including V1 access patterns.

This is important because teams can use the usage history to answer questions like:

  • which integration patterns are active,
  • whether API traffic is increasing,
  • whether external consumers are contributing materially to quota consumption.

That makes integration governance measurable instead of theoretical.

Recommended integration maturity model

Start with the built-in surfaces

If the workspace workflow is still changing, use the default dashboard and public workspace first.

Add API access when the data model is stable enough

Once the team understands its content, agent, and publishing structure, API access becomes much safer and more useful.

Use workspace snapshots and published article endpoints for delivery

If the goal is a custom front end or external publication surface, start with published content and workspace snapshot data rather than trying to reproduce the entire internal operating model externally.

Governance guidance

API access should be governed like any other privileged capability.

That means:

  • create keys intentionally,
  • keep the number of active keys low,
  • review who or what owns each key,
  • monitor usage records for API-driven activity,
  • delete unused or outdated keys.

The broader rule is simple: programmatic access is still workspace access.

Common mistakes to avoid

  • Exposing API access before the internal workflow is stable enough to support it.
  • Treating API keys like disposable convenience tokens.
  • Building external consumers without monitoring their usage impact.
  • Assuming the API is a separate system instead of an extension of workspace governance.

How this page connects to the rest of the handbook

Use this page together with:

Related guides