> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pcnaid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# EntityShield API surface

> EntityShield HTTP route families, access rules, and outbound-webhook integration — covering the admin, workspace, staff, and governance namespaces.

# EntityShield API surface

The production API base is `https://api.entityshield.app`. The API exposes **148 route mounts** across 147 route files, grouped into public, admin, workspace, staff, and governance route families.

## Public endpoints

These endpoints are mounted before the authentication middleware:

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/health` | Service name, version, environment, timestamp |
| `GET` | `/v1/public/avatars` | Public avatar serving |
| `GET` | `/v1/public/workspaces/:slug/branding` | Workspace public branding |
| `GET` | `/v1/public/forms` | Public intake forms |
| `GET` | `/v1/public/landing` | Landing page data |
| `GET` | `/ics/:feedId` | iCal feed |

Inbound webhook receivers (for example, Stripe billing events) are also handled before the authentication middleware.

Try the health check with curl:

```bash theme={null}
curl https://api.entityshield.app/health
```

## Authentication

Most application routes begin with `/v1`. The API applies Auth0 JWT verification to `/v1/*` after the public routes. Four token audiences are distinguished:

| Audience | Namespace | Scope |
| - | - | - |
| `https://api.entityshield.app` | `/v1/` | Admin + workspace routes |
| `https://api.entityshield.app` | `/v1/workspace/*` | Workspace-audience routes |
| `https://staff.entityshield.app` | `/v1/staff/*` | Staff-audience routes |
| `https://gov.entityshield.app` | `/v1/governance/*` | Governance-audience routes |

There is no general-purpose public API key issuance flow. Access is enforced by audience, tenant or workspace membership, and route-specific permissions.

## Core admin route families

| Methods | Path | Purpose | Permission |
| - | - | - | - |
| `GET`, `POST` | `/v1/entities` | List or create entities | `entities:read`, `entities:write` |
| `GET`, `PATCH` | `/v1/entities/:entityId` | Read or update one entity | Entity membership checks |
| `GET`, `POST` | `/v1/locations` | List or create locations | `locations:read`, `locations:write` |
| `GET`, `PATCH`, `DELETE` | `/v1/locations/:locationId` | Read, update, soft-delete | Per-operation |
| `GET`, `POST` | `/v1/permits` | List or create permits | `permits:read`, `permits:write` |
| `GET`, `PATCH`, `DELETE` | `/v1/permits/:permitId` | Read, update, soft-delete | Per-operation |
| `GET`, `POST` | `/v1/governance-filings` | List or create filings | `governance:read`, `governance:write` |
| `GET`, `PATCH`, `DELETE` | `/v1/governance-filings/:filingId` | Read, update, soft-delete | Per-operation |
| `GET`, `POST` | `/v1/dbas` | List or create DBAs | `dbas:read`, `dbas:write` |
| `GET`, `PATCH`, `DELETE` | `/v1/dbas/:dbaId` | Read, update, soft-delete | Per-operation |
| `GET`, `POST` | `/v1/ip-assets` | List or create IP assets | `ip:read`, `ip:write` |
| `GET`, `PATCH`, `DELETE` | `/v1/ip-assets/:assetId` | Read, update, soft-delete | Per-operation |
| `GET`, `POST` | `/v1/tasks` | List or create tasks | `tasks:read`, `tasks:write` |
| `GET`, `PATCH`, `DELETE` | `/v1/tasks/:taskId` | Read, update, task-detail | Per-operation |
| `GET` | `/v1/dashboard` | Dashboard summary data | Authenticated |
| `GET` | `/v1/dashboard/compliance-health` | Compliance health scores | Authenticated |
| `GET`, `POST` | `/v1/users` | List or manage users | `users:read`, `users:write` |
| `GET`, `PATCH` | `/v1/users/me` | Current user profile | Authenticated |
| `GET`, `POST` | `/v1/entity-members` | Entity membership CRUD | `members:manage` |
| `GET`, `POST` | `/v1/invitations` | Entity invitations | `invitations:manage` |
| `GET`, `POST` | `/v1/billing` | Billing subscription, invoices, usage | `billing:read` |
| `GET`, `POST` | `/v1/billing/checkout-session` | Create Stripe checkout | `billing:write` |
| `POST` | `/v1/billing/portal-session` | Stripe Customer Portal | `billing:write` |
| `GET`, `POST` | `/v1/webhook-endpoints` | Outbound webhook management | `admin:webhooks` |
| `GET`, `POST` | `/v1/documents` | Document vault CRUD | `documents:read`, `documents:write` |
| `GET`, `POST` | `/v1/calendar` | Calendar events and deadlines | Authenticated |
| `GET`, `POST` | `/v1/calendar-feeds` | iCal feed management | Authenticated |
| `GET`, `POST` | `/v1/calendar-sync` | Google Calendar sync | Authenticated |
| `GET`, `POST` | `/v1/notifications` | Notification preferences | `notifications:read` |
| `GET`, `POST` | `/v1/ai` | AI assistant sessions | Authenticated |
| `GET`, `POST` | `/v1/ai/images` | AI image generation | Authenticated |
| `GET`, `POST` | `/v1/ai/research` | AI research reports | Authenticated |
| `GET`, `POST` | `/v1/ai/askai` | AI Q\&A | Authenticated |
| `GET`, `POST` | `/v1/taxonomies` | Reference taxonomies | Authenticated |
| `GET`, `POST` | `/v1/entity-taxonomy` | Entity taxonomy mapping | Authenticated |
| `GET`, `POST` | `/v1/import-jobs` | Bulk import management | `imports:manage` |
| `GET`, `POST` | `/v1/export-jobs` | Data export management | `exports:read` |
| `GET`, `POST` | `/v1/saved-filters` | Saved filter CRUD | Authenticated |
| `GET`, `POST` | `/v1/entity-structure` | Entity structure/hierarchy | `entities:read` |
| `GET` | `/v1/reports/compliance` | Compliance report | `reports:read` |
| `GET` | `/v1/reports/renewals` | Renewals report | `reports:read` |
| `GET` | `/v1/reports/ip-portfolio` | IP portfolio report | `reports:read` |
| `GET` | `/v1/reports/activity` | Activity report | `reports:read` |
| `GET` | `/v1/reports/plan-usage` | Plan usage report | `billing:read` |

## Workspace namespace

Workspace routes are scoped through workspace identity and membership. They are prefixed with `/v1/workspace/portal/` and cover modules for operations, team, inbox, reputation, marketing, inventory, helpdesk, social, support, reports, settings, and AI:

| Area | Mount path |
| - | - |
| Home | `/v1/workspace/portal/home` |
| Tasks | `/v1/workspace/portal/tasks` |
| Calendar | `/v1/workspace/portal/calendar` |
| Inbox | `/v1/workspace/portal/inbox` |
| Permits | `/v1/workspace/portal/permits` |
| Drive | `/v1/workspace/portal/drive` |
| Team | `/v1/workspace/portal/team/people` |
| Team schedule | `/v1/workspace/portal/team/schedule` |
| Settings | `/v1/workspace/portal/settings` |
| Support | `/v1/workspace/portal/support` |
| Marketing | `/v1/workspace/portal/marketing` |
| Social | `/v1/workspace/portal/social` |
| Reputation | `/v1/workspace/portal/reputation` |
| Inventory | `/v1/workspace/portal/inventory` |
| Helpdesk | `/v1/workspace/portal/helpdesk` |
| Reports | `/v1/workspace/portal/reports` |
| AI | `/v1/workspace/portal/ai` |

## Staff namespace

Staff routes are prefixed with `/v1/staff/` and require staff-audience tokens. They support Pcnaid staff cross-tenant operations such as customer management, user management, and support.

## Governance namespace

Governance routes are prefixed with `/v1/governance/` and scoped by governance identity and entity membership. They include governance portal data, meetings, and video support.

## Outbound webhooks

The webhook endpoints are managed at `/v1/webhook-endpoints`. Users with `admin:webhooks` can list events, create destinations, inspect deliveries, test, and replay:

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/v1/webhook-endpoints/events` | List supported event names |
| `GET`, `POST` | `/v1/webhook-endpoints` | List or create destinations |
| `GET`, `PATCH`, `DELETE` | `/v1/webhook-endpoints/:endpointId` | Read, update, delete |
| `POST` | `/v1/webhook-endpoints/:endpointId/rotate-secret` | Rotate signing secret |
| `POST` | `/v1/webhook-endpoints/:endpointId/test` | Send test event |
| `GET` | `/v1/webhook-endpoints/deliveries` | List delivery attempts |
| `POST` | `/v1/webhook-endpoints/deliveries/:deliveryId/replay` | Replay delivery |

Destination URLs are checked against the server's SSRF guard. Delivery payloads are HMAC-SHA256 signed.

***

> [!NOTE]
>
> An OpenAPI document, stable public error-code catalog, public rate-limit contract, and third-party API key onboarding flow are not yet published.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.