Discovery and resources

Workspace integrations should discover capabilities and resources at runtime. This keeps clients stable when a server publishes additional capabilities or omits optional contracts.

Use this reference when you connect a custom client, automation, integration, or agent to Workspace. After reading it, you can select the correct public or authenticated discovery surface and use the system tenant resource without constructing API paths locally.

Public discovery

Read public discovery before authentication:

bash

nucli --host https://workspace.example discovery --json
nucli --host https://workspace.example api --anonymous GET /api/v1/meta/entrypoints --summary

GET /api/v1/meta/discovery reports the API major, server version, build metadata, and public capabilities. GET /api/v1/meta/entrypoints reports public authentication and onboarding entrypoints. Treat versions and build timestamps as diagnostics. Use capabilities and published entrypoints as the runtime contract.

Authenticated resources

After login, read tenant-bound resource entrypoints from GET /api/v1/profile/entrypoints:

bash

nucli --tenant <tenant> resources list
nucli --tenant <tenant> resources meta <entrypoint-id>
nucli --tenant <tenant> resources get <entrypoint-id>

For entries with kind: crud, read metaHref before building payloads. Use only the methods and URLs declared by the server. If an entry or action is missing, stop instead of trying a guessed legacy path.

Discover the system tenant resource

Clients operating in the system tenant can discover tenant administration in the same authenticated response. Select the stable system.tenants entry and use only its published actions:

json

{
  "id": "system.tenants",
  "kind": "system-resource",
  "href": "/api/v1/system/tenants",
  "actions": [
    {
      "id": "list",
      "method": "GET",
      "href": "/api/v1/system/tenants"
    },
    {
      "id": "read",
      "method": "GET",
      "href": "/api/v1/system/tenants/{id}"
    },
    {
      "id": "create",
      "method": "POST",
      "href": "/api/v1/system/tenants",
      "requiredHeaders": ["Idempotency-Key"],
      "acceptedStatus": 202,
      "responseHeaders": ["Location", "Retry-After"],
      "statusHref": "/api/v1/system/tenants/{tenantId}/provisioning",
      "statusRequiredAnyScopes": [
        "tenants:read",
        "system_diagnostics:read"
      ]
    }
  ]
}

The response contains only actions allowed by the current session:

Action	Required scope
`list`	`tenants:list`
`read`	`tenants:read`
`create`	`tenants:create`

Send Idempotency-Key when creating a tenant. An accepted request returns 202 Accepted and points to provisioning status through Location. Retry-After can indicate when to poll again. Poll status only when the session has at least one scope listed in statusRequiredAnyScopes. A session with only tenants:create can start provisioning but may not read its status.

The entry is absent outside the system tenant, when the authoritative tenant type cannot be confirmed, or when no action scope is available. It never appears in public pre-auth discovery. Treat a missing entry or action as a definitive denial. Do not infer update, delete, or other system paths from the collection URL.

After creation, verify that Location refers to the new tenant and wait for a terminal provisioning status before starting dependent setup work.

Use Create a tenant for the ready-to-use discovery-based CLI and MCP workflow. Custom integrations must still evaluate the published action described here and fail closed when its method, path, or status contract differs.

Integration rules

Check capabilities before using optional functions.
Use whoami and scopes before a script changes data.
Do not store unredacted API responses with personal or contact data in broadly readable files.
Keep unknown entrypoint kinds fail-closed.