Control-plane resource map
Navigate the real Den API resource families for organizations, configuration, marketplaces, connectors, skills, and managed Workers.
The Den API is iPolloWork's organization control plane. It owns identity, organization membership, shared configuration, access grants, managed providers, connector state, and hosted Workers. It does not own a person's arbitrary local filesystem or substitute for the Local Server API.
A resource has a lifecycle, a stable ID, and an access model. Keep account identity, reusable configuration, external connections, and runtime work as separate objects.
Who may act
`/v1/me`, `/v1/me/orgs`, and `/v1/org` establish the active organization context.
Represent membership and delegated access separately from a session credential.
What may be reused
Addressable configuration with lifecycle, history, plugin relationships, and grants.
Reusable capability containers with their own resolution and access routes.
Where work can run or synchronize
Account, instance, target, mapping, discovery, and sync events remain separate objects.
Optional organization-managed runtime resources with their own runtime status and activity.
Begin every integration with identity
The stable integration order is:
- Authenticate and call
GET /v1/me. - Read organizations through
GET /v1/me/orgsand select the intended organization context. - Discover the resource collection with a bounded list route and server filters.
- Write the smallest resource mutation using an immutable resource ID.
- Re-read the resource, its version, resolved view, activity, or sync event.
The display name in a UI is context, not a durable primary key. Persist IDs returned by the API.
- 01Authenticate
Establish caller identity through the scheme required by the route.
- 02Scope
Resolve the active organization and verify the caller can see the target collection.
- 03Constrain
Use pagination, type, status, and connector or plugin filters before retrieving records.
- 04Compose
Create, connect, grant, resolve, or archive one resource family at a time, then re-read.
Resource families and actual route groups
| Resource family | Key routes | Lifecycle guidance |
|---|---|---|
| Identity and administration | /v1/me, /v1/me/orgs, /v1/org, /v1/api-keys, members, invitations, teams, roles | Read the caller and organization first. Treat API keys and delegated roles as security-sensitive admin resources. |
| Model providers | /v1/llm-provider-catalog, /v1/llm-providers | Select a catalog capability, create the provider record, then connect or grant access according to policy. |
| Config objects | /v1/config-objects, versions, access, plugins, archive/delete/restore routes | Preserve version history and use the exact latest, version, or resolved endpoint needed by the runtime. |
| Plugins and marketplaces | /v1/plugins, /v1/marketplaces, resolved, access, and relationship routes | Keep publication, resolution, membership, and access as explicit operations. |
| Skills and Skill Hubs | /v1/skills, /v1/skill-hubs and assignment/access routes | Use a Skill Hub for a reusable collection; use an individual Skill for a distinct unit. |
| Connectors | accounts, instances, targets, mappings, discovery, sync events | Preserve the account → instance → target → mapping graph so failed synchronization can be retried at the right node. |
| Workers | /v1/workers, runtime, tokens, activity heartbeat | Use only for organization-managed runtime; a normal local desktop workspace does not require a Worker. |
Configuration is versioned state, not a blob
GET /v1/config-objects is a discovery route. It supports cursor pagination, a limit from 1 through 100, type, status, sourceMode, plugin and connector-instance filters, deleted-resource selection, and a text query. Use those filters on the server rather than fetching an unbounded client list.
The individual object, version history, latest version, and resolved form serve different purposes. A runtime needs the resolved representation only when it is ready to consume configuration. An editor may need a particular version. A list view usually needs neither full history nor a resolved payload.
The control plane can retain history without making every historical object live at runtime.
- 01Create
Create the addressable configuration object with its type and metadata.
- 02Version
Add a version and keep the historical record rather than overwriting unknown state.
- 03Grant
Attach the narrow access and plugin relationships needed by the intended audience.
- 04Resolve or retire
Read the resolved form for runtime use, or archive/delete/restore through the lifecycle route.
Connectors and Workers are asynchronous systems
Use the resource ID returned by a connector, discovery, sync, or Worker request to query the current object. Creation or an accepted response proves the request was received; it does not prove remote discovery, synchronization, or runtime readiness has completed. The retriable object is often a sync event or target, not the original account.
For route-specific schemas, response status, and security schemes, use the repository's generated OpenAPI contract. Then continue with OpenAPI and integration and Runtime and webhooks.