iPolloWork Docs

OpenAPI and integration

Use the control-plane OpenAPI contract without confusing it with the local workspace server.

The control-plane API is described by the repository OpenAPI document at packages/docs/openapi.json. It is a versioned contract for organization and Cloud capabilities, including identity, configuration resources, plugins, Skills, connectors, and hosted workers.

The document reference is authoritative for a route's schema. This guide explains how to choose the surface, authenticate, form a safe client, and handle the lifecycle semantics that appear across resource families.

Integration boundaryChoose the API by the state it owns

A control-plane request should not be used as an indirect way to manipulate local workspace files. A local server request should not be used as organization administration.

01
Client

Your desktop, web, CLI, or service client

User action

An explicit person or service intent begins the request.

Scoped credential

Send only the authorization material appropriate for this API call.

02
Control plane

The Den OpenAPI contract

Identity and organization

Resolve the current person, organization, member, role, or invitation.

Capability resources

Version and grant configuration objects, plugins, Skills, providers, and connectors.

Managed runtime

Provision and inspect hosted Workers only where a remote runtime is required.

03
Local work

A different runtime boundary

Local server API

Access the workspace, approvals, artifacts, status, and supported OpenCode proxy.

Read the generated OpenAPI schema before implementing a write. This guide does not replace per-route request and response definitions.

Base URL and paths

The OpenAPI server declaration currently points to https://api.ipolloworklabs.com. The Cloud desktop documentation also uses a configured web base URL to derive paths such as:

https://app.ipolloworklabs.com/api/den/v1/...
https://app.ipolloworklabs.com/api/den/mcp/...

Use the actual configured base URL for the deployment you are targeting. Do not hard-code a public address into a client that must run against a private organization environment.

Authenticate deliberately

The contract declares two supported security schemes. A route can require one of them according to its OpenAPI definition.

SchemeHeaderUse it when
Bearer sessionAuthorization: Bearer <session-token>Acting as a signed-in person or desktop session.
Den API keyx-api-key: <den-api-key>A service integration has been issued an organization API key.

Never place either value in a browser-visible static artifact, source repository, shared screenshot, or support log. For a first connectivity check, use a non-secret endpoint if the OpenAPI route declares it public:

curl --fail-with-body https://api.ipolloworklabs.com/health

After a secure credential is supplied through the client environment, resolve the caller before showing protected actions:

curl --fail-with-body \
  -H "Authorization: Bearer $IPOLLOWORK_SESSION_TOKEN" \
  https://api.ipolloworklabs.com/v1/me

Build the request loop

Client request loopDiscover, constrain, write, then re-read

Most integration mistakes come from writing against the wrong organization context or assuming a display name is a stable identifier.

  1. 01Discover

    Read the current person, organizations, and the resource collection with its real filters.

  2. 02Constrain

    Select organization scope, resource ID, permission, and the exact request schema from OpenAPI.

  3. 03Write

    Create, update, archive, restore, or provision through the narrow resource route.

  4. 04Re-read

    Fetch the returned ID, version, resolved representation, or activity state before the next action.

Pagination, filters, and status behavior

Resource collections expose route-specific query shapes. For example, GET /v1/config-objects accepts cursor pagination, limit from 1 through 100, a resource type, status, sourceMode, plugin and connector filters, deleted-resource selection, and a text query. GET /v1/workers also uses cursor pagination, with a limit from 1 through 50.

The exact defaults and response envelope belong to the OpenAPI schema. Client code should:

  1. Preserve the cursor returned by the previous page instead of manufacturing offsets.
  2. Treat a zero-result collection as a valid result, not as an authorization failure.
  3. Render 401, 403, 409, and 422 as distinct actionable states when a route declares them.
  4. Keep an operation ID or resource ID in logs, but never log credentials or raw provider secrets.

What to use as the source of truth

QuestionBest source
Required request fields and exact response bodypackages/docs/openapi.json for the checked-out iPolloWork revision
Organization, membership, or access behaviorThe matching /v1 resource family and its OpenAPI operation
Local file, session, approval, or artifact operationThe local iPolloWork server API, not the Den API
Remote worker readiness and token behaviorThe Worker operations in the OpenAPI contract

Continue with Authentication and access for scope decisions and Runtime, workers, and webhooks for asynchronous lifecycle work.

On this page

Base URL and pathsAuthenticate deliberatelyBuild the request loopPagination, filters, and status behaviorWhat to use as the source of truth