Public CMS API

Externa exposes a headless Public CMS API under /api/v1 so websites, apps, and integrations can read (and optionally write) collection data without an admin session. Access is controlled by a separate permission model from Spatie admin permissions.

Full setup walkthrough is below. Endpoint tables with request/response examples and the Bruno companion are at the end. Copyable TypeScript / OpenAPI / JSON Schema: Public CMS API client types. Minimal frontends: Headless starter (Next.js + Nuxt). Ops: Performance tuning. Related admin concepts: Roles & permissions, Effective permissions. 1.x stability / deprecation: API & GraphQL compatibility.

Mental model

Request to /api/v1/...
        │
        ▼
┌───────────────────────┐
│ ResolveApiAccess      │
│  • Bearer ek_… ?      │──yes──► validate key → role on api_keys.role_id
│  • no Bearer          │──no───► actor = public role
└───────────────────────┘
        │
        ▼
┌───────────────────────┐
│ CollectionPermission  │  Missing grant = DENY
│ Guard / FilePermission│  Actions: create | read | read_private | update | delete
│ Guard (cached)        │  Files are global; private visibility is per-file
└───────────────────────┘
        │
        ▼
 Controller runs (or 403)

Default deny: if there is no row in collection_permissions for (role_id, collection_id, action), or in file_permissions for (role_id, action), the action is forbidden.

Quick start (typical website read)

Goal: a public site can GET collections/items for posts, but cannot create/update/delete.

1. Sign in as an admin who can edit roles (can-edit-roles).
2. Open Roles → edit the public role (system role; cannot be deleted, renamed, or assigned to users).
3. In Collection access, set Read to allowed (✓) for the collections you want public. Leave Create / Update / Delete as denied (✕).
4. Optionally open Files access and grant Read if the site needs /api/v1/files* or expanded image URLs on items. Grant Read private only for roles that should see files marked private in the file manager.
5. Save.
6. Call without a key:

curl -sS http://externa-core.test/api/v1/collections \
  -H 'Accept: application/json'

curl -sS http://externa-core.test/api/v1/collections/posts/items \
  -H 'Accept: application/json'

7. Confirm mutations fail:

curl -sS -X POST http://externa-core.test/api/v1/collections/posts/items \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"data":{}}'
# → 403

Setup guide (full)

1. Ensure migrations and seeds ran

You need:

• Role public (is_system, is_assignable = false) from RoleSeeder
• Tables collection_permissions, file_permissions, and api_keys
• Spatie permissions can-show-api-keys / can-manage-api-keys (via permissions:sync)

php artisan migrate
php artisan permissions:sync
php artisan db:seed --class=RoleSeeder   # if public role is missing

2. Configure anonymous (public) access

3. Create a role for partners / backends (optional)

For write access or private read without opening the internet to everyone:

1. Roles → Create a normal role (e.g. api-website, api-partner).
2. You may leave Spatie admin permissions empty — they do not affect /api/v1.
3. Set Collection access for the collections/actions that key should have.
4. Set Files access if the key should list/upload/stream files.
5. Save.

4. Issue an API key

Scopes only narrow the role (effective = role ACL ∩ key scopes). Rate limits, cost budget, payload caps: API abuse controls & key scopes.

curl -sS http://externa-core.test/api/v1/collections \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ek_YOUR_SECRET"

5. Point your client / Bruno

• Base URL: your app URL (e.g. http://externa-core.test or staging)
• Paths always under /api/v1/...
• Clone externa-bruno: open the folder in Bruno, env Local (or a copy for staging), .env → EXTERNA_API_KEY, then set collection_slug / item_id / file_id on requests

How authentication is resolved

Middleware: App\Http\Middleware\ResolveApiAccess on all routes/api.php v1 routes.

No Bearer token → public

• Loads role named public
• If missing → 503 (Public API role is not configured.)
• Binds ApiAccess with actor = public

Bearer token → API key

1. Hash the secret and look up api_keys
2. Reject if missing, revoked, or expired → 401
3. Enforce optional IP allowlist → 401 if client IP not listed
4. Enforce rate limit (key override or API_KEY_RATE_LIMIT, default 60/min) → 429 (API key rate limit exceeded.)
5. Reject if linked role is super-admin → 401
6. Bind ApiAccess with actor = api_key and that role
7. Touch last_used_at

Route group also uses Laravel throttle:api (60/min by user or IP) and ApiRequestCostMiddleware (optional cost budget / body cap). Full table and 429 examples: API abuse controls.

Collection access matrix

Stored in collection_permissions:

Service: CollectionPermissionGuard (cached per role; flushed when the role matrix is saved via CollectionPermissionSync).

UI: role create/edit → Collection access table. Toggle buttons show ✓ (allowed) or ✕ (denied).

Files access matrix

Stored in file_permissions (global per role — not per folder):

Service: FilePermissionGuard / FilePermissionSync. UI: role create/edit → Files access.

Public vs private files

Each file/folder has an access override (files.access): public, private, or null (inherit from nearest ancestor). Effective visibility walks parents; root with no override is public.

Admin file manager (Spatie can.manage.files) always sees all files; use the Visibility control on the detail panel (Inherit / Public / Private). Private folders apply to children unless a child overrides.

Storage: effective-private local files use the private_assets disk (not /storage/assets/...). Public CMS clients always receive gated /api/v1/files/{id}/content URLs (never a static public object URL for private files). Operators: run php artisan files:migrate-private-disk after upgrade if legacy private bytes remain on assets — Files configuration.

Endpoint reference

Base path: /api/v1. Controllers under App\Http\Controllers\Api\V1\. Examples use http://externa-core.test and a sanitized key ek_YOUR_SECRET — replace with your Herd host and real key.

Auth header when using an API key (omit for anonymous / public role):

Authorization: Bearer ek_YOUR_SECRET
Accept: application/json

Collections

List collections

curl -sS http://externa-core.test/api/v1/collections \
  -H 'Accept: application/json'
# optional: -H "Authorization: Bearer ek_YOUR_SECRET"

{
  "data": [
    {
      "id": 1,
      "name": "Posts",
      "slug": "posts",
      "is_singleton": false
    }
  ]
}

With no read grants: "data": [] (still 200, not 403).

Get collection

curl -sS http://externa-core.test/api/v1/collections/posts \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ek_YOUR_SECRET"

{
  "data": {
    "id": 1,
    "name": "Posts",
    "slug": "posts",
    "is_singleton": false,
    "fields": [
      {
        "id": 10,
        "name": "title",
        "type": "text",
        "settings": {}
      },
      {
        "id": 11,
        "name": "status",
        "type": "select",
        "settings": {}
      }
    ]
  }
}

Items

List items

curl -sS 'http://externa-core.test/api/v1/collections/posts/items?page=1&per_page=15' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ek_YOUR_SECRET"

Advanced filter (same dialect as admin / GraphQL):

curl -sS 'http://externa-core.test/api/v1/collections/posts/items?filter[status][_eq]=published&page=1&per_page=15' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ek_YOUR_SECRET"

Also: filter[title][_contains]=hello, filter[status][_in]=published,draft, filter[body][_nnull]=1. See Advanced list filters.

{
  "data": [
    {
      "id": 1,
      "collection_id": 3,
      "data": { "title": "Hello", "status": "published" },
      "created_at": "2026-07-20T12:00:00+00:00",
      "updated_at": "2026-07-20T12:00:00+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 15,
    "total": 1
  }
}

Get item

curl -sS http://externa-core.test/api/v1/collections/posts/items/1 \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ek_YOUR_SECRET"

{
  "data": {
    "id": 1,
    "collection_id": 3,
    "data": {
      "title": "Hello",
      "status": "published"
    },
    "created_at": "2026-07-20T12:00:00+00:00",
    "updated_at": "2026-07-20T12:00:00+00:00"
  }
}

Optional query: locale, include_all_translations, include (see Expand with include and the query table below).

Create item

curl -sS -X POST http://externa-core.test/api/v1/collections/posts/items \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ek_YOUR_SECRET" \
  -d '{"data":{"title":"New post","status":"draft"}}'

{
  "data": {
    "id": 42,
    "collection_id": 3,
    "data": {
      "title": "New post",
      "status": "draft"
    },
    "created_at": "2026-07-20T12:00:00+00:00",
    "updated_at": "2026-07-20T12:00:00+00:00"
  }
}

Status 201. M2M junction values use { "related_item_id": 12, "meta": { "sort": 1 } } — see M2M junction metadata. Nested blocks payloads: Field types — Blocks.

Update item

curl -sS -X PATCH http://externa-core.test/api/v1/collections/posts/items/42 \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ek_YOUR_SECRET" \
  -d '{"data":{"title":"Updated title","status":"published"}}'

Response 200 — same item shape as Get item.

From externa-core 1.3.0 (PR #293), PATCH is a partial update: omitted fields and locales are kept (merged over the assembled current values). Value sync runs in a DB transaction. To clear a field, send null explicitly — clients that relied on PATCH wiping omitted fields must change.

Delete item

curl -sS -X DELETE http://externa-core.test/api/v1/collections/posts/items/42 \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ek_YOUR_SECRET"

Response 204 — empty body (soft-delete).

Batch writes

From externa-core 1.4.0 (#125), create, update, or soft-delete up to API_MAX_BATCH_SIZE items (default 100) in one request:

curl -sS -X POST http://externa-core.test/api/v1/collections/posts/items/batch \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ek_YOUR_SECRET" \
  -d '{"items":[{"data":{"title":"One"}},{"data":{"title":""}}]}'

{
  "data": [
    {
      "index": 0,
      "ok": true,
      "item": { "id": 51, "collection_id": 3, "data": { "title": "One" } }
    },
    {
      "index": 1,
      "ok": false,
      "error": {
        "message": "The title field is required.",
        "status": 422,
        "errors": { "title": ["The title field is required."] }
      }
    }
  ],
  "meta": { "total": 2, "succeeded": 1, "failed": 1 }
}

• Each entry is atomic on its own; there is no all-or-nothing transaction across entries. The response is 200 even when some entries fail; check ok / meta.failed. Delete results carry id instead of item.
• The collection action is checked once for the request (403 when missing); item-level rules (item filter, field rules, writable fields) are checked per entry.
• Entries run through the same create/update actions as single writes (validation, draft versioning, per-item activity log) and fire the existing item.* webhooks per item. There are no batch webhook event types.
• An empty list or more than API_MAX_BATCH_SIZE entries returns 422. With the cost budget on, a batch costs one mutation (API_COST_MUTATION), not one per entry.

GraphQL has no batch mutation.

Files

List files

curl -sS 'http://externa-core.test/api/v1/files?page=1&per_page=15' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ek_YOUR_SECRET"

{
  "data": [
    {
      "id": 12,
      "parent_id": null,
      "type": "file",
      "access": "public",
      "filename": "hero.jpg",
      "title": "Hero",
      "description": null,
      "mime_type": "image/jpeg",
      "extension": "jpg",
      "filesize": 204800,
      "width": 1920,
      "height": 1080,
      "focal_point_x": 0.5,
      "focal_point_y": 0.5,
      "url": "http://externa-core.test/api/v1/files/12/content",
      "transforms": {
        "thumbnail": "http://externa-core.test/api/v1/files/12/transforms/thumbnail",
        "card": "http://externa-core.test/api/v1/files/12/transforms/card"
      },
      "created_at": "2026-07-20T12:00:00+00:00",
      "updated_at": "2026-07-20T12:00:00+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 15,
    "total": 1
  }
}

transforms keys match Settings → Files & Media presets (defaults: thumbnail, small, medium, card). Full guide: Image transforms.

Query: parent_id, search, page, per_page (1–100). Private rows are omitted without read_private (still 200).

Get file

curl -sS http://externa-core.test/api/v1/files/12 \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ek_YOUR_SECRET"

Response 200 — { "data": { … } } same shape as a list row. Private file without read_private → 403.

Get file content / transform

curl -sS -OJ http://externa-core.test/api/v1/files/12/content \
  -H "Authorization: Bearer ek_YOUR_SECRET"

curl -sS -OJ http://externa-core.test/api/v1/files/12/transforms/thumbnail \
  -H "Authorization: Bearer ek_YOUR_SECRET"

Streams bytes (Content-Type from the file / transform). Same auth rules as Get file. Presets, size-{n}, focal point, and caching: Image transforms.

Upload file

curl -sS -X POST http://externa-core.test/api/v1/files \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ek_YOUR_SECRET" \
  -F 'file=@/path/to/image.jpg' \
  -F 'parent_id=' \
  -F 'name='

Multipart field file (required). Optional parent_id, name. Response 201 — { "data": { …FileResource } } (same shape as Get file).

Update file

curl -sS -X PATCH http://externa-core.test/api/v1/files/12 \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ek_YOUR_SECRET" \
  -d '{"title":"Hero","description":"Updated via Public CMS API","focal_point_x":0.35,"focal_point_y":0.6}'

Allowed metadata: title, description, location, download_name, focal_point_x / focal_point_y (0–1), name. Response 200 — updated FileResource.

Delete file

curl -sS -X DELETE http://externa-core.test/api/v1/files/12 \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ek_YOUR_SECRET"

Response 204 — empty body (soft delete).

Expand with include

Public REST item list/show responses are lean by default. File objects, mini-users, and related items are expanded only when you opt in with ?include=… (CSV, case-sensitive). GraphQL is unchanged (still expands files). Admin Inertia keeps raw IDs.

GET /api/v1/collections/{slug}/items?include=files,author,categories
GET /api/v1/collections/{slug}/items/{id}?include=files

Unknown tokens and non-relation field names are ignored (no 400). Nested hydrated items do not re-apply relation includes; they may still apply files / users if those tokens are in the same include list.

From externa-core 1.3.0, item list endpoints batch-prewarm relation targets once per response (RelationIncludeHydrator::prewarm, core#112) so depth-1 query count stays flat as parent N grows. Prefer lean includes for payload size — Performance tuning.

Default shape (no include)

• data: raw stored values — files = id or [id, …]; relations = int / [{ related_item_id, meta }] / m2a links
• user_created / user_updated: null

With include

File expansion (only with include=files):

• With file:read on a public file: object(s) with id, filename, title, mime_type, width, height, filesize, url, transforms
• Without file:read on a public file: { "id": N, "access": "denied" } (no URLs) — breaking vs older { "id": N } only
• Private file without file:read_private: null (single) or omitted from files arrays — no id or url
• Soft-deleted / missing files → null (or omitted from files arrays)

Permissions: related items hydrate only when readable for the actor (CollectionPermissionEnforcer). Unreadable → leave raw id / junction / m2a link (no nested payload).

Examples

# Lean list (file fields are IDs)
curl -sS 'http://externa-core.test/api/v1/collections/posts/items?page=1&per_page=15' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ek_YOUR_SECRET"

# Expand files + author relation + mini-users
curl -sS 'http://externa-core.test/api/v1/collections/posts/items/1?include=files,author,users' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ek_YOUR_SECRET"

{
  "data": {
    "id": 1,
    "collection_id": 3,
    "data": {
      "title": "Hello",
      "cover": {
        "id": 12,
        "filename": "hero.jpg",
        "title": "Hero",
        "mime_type": "image/jpeg",
        "width": 1920,
        "height": 1080,
        "filesize": 204800,
        "url": "http://externa-core.test/api/v1/files/12/content",
        "transforms": {
          "thumbnail": "http://externa-core.test/api/v1/files/12/transforms/thumbnail",
          "card": "http://externa-core.test/api/v1/files/12/transforms/card"
        }
      },
      "author": {
        "id": 7,
        "collection_id": 2,
        "data": { "name": "Ada" },
        "created_at": "2026-07-20T12:00:00+00:00",
        "updated_at": "2026-07-20T12:00:00+00:00",
        "user_created_id": null,
        "user_updated_id": null,
        "user_created": null,
        "user_updated": null
      }
    },
    "created_at": "2026-07-20T12:00:00+00:00",
    "updated_at": "2026-07-20T12:00:00+00:00",
    "user_created_id": 1,
    "user_updated_id": 1,
    "user_created": { "id": 1, "name": "Admin", "email": "admin@example.com" },
    "user_updated": { "id": 1, "name": "Admin", "email": "admin@example.com" }
  }
}

TypeScript / OpenAPI shapes: Public CMS API client types. Bruno: List / Get Item with include query.

Query parameters (items)

With ?locale= (or the resolved active locale) and include_all_translations unset/false, each top-level translatable field is a single scalar: first usable value along requested → enabled fallback_content_locales → APP_FALLBACK_LOCALE (if enabled) → null. Empty strings are treated as missing. Nested block fields stay as per-locale maps.

Permission → behaviour cheat sheet

HTTP errors

CORS and config

API_KEY_RATE_LIMIT=60
CORS_ALLOWED_ORIGINS=https://www.example.com,https://staging.example.com

Configure the project allowlist in Settings → Project → Public API (not only via env). Full behavior, Bruno notes, and security limits: Client types — Origin allowlist.

Admin UI surfaces

Admin Spatie permissions for the API Keys screen:

can-show-api-keys
can-manage-api-keys

Bruno collection (externa-bruno)

Ready-to-use companion: https://github.com/qiick-io/externa-bruno — classic Bruno layout (bruno.json + folders). Docs above are the source of example payloads; Bruno executes them.

1. Install Bruno, clone / open the externa-bruno folder as a collection
2. Select environment Local (environments/Local.bru; default base_url = http://externa-core.test)
3. Copy .env.sample → .env, set EXTERNA_API_KEY (and EXTERNA_WEBHOOK_SECRET if needed)
4. Set request vars collection_slug / item_id / file_id as needed
5. Staging / remote: duplicate Local in Bruno, set base_url (no trailing slash) and the matching key in .env
6. Folder PublicApi inherits Bearer auth from folder.bru (except List Collections Anonymous, which uses auth: none)
7. If Allowed origins is set in project settings, Bruno calls without an Origin header require a valid api_key (anonymous requests will 403)
8. Subfolders: Files, GraphQL, Webhooks (Verify Webhook Signature — sample payload / signing helper; default __webhook_receiver_docs_only__ URL is a placeholder and 404s on externa-core; see Outbound webhooks)

Each request includes a docs panel describing method, auth, required permission, and expected status codes. Full open notes: externa-bruno README.

Tests

• Pest feature suites: PublicCollectionApiTest, PublicFilesApiTest, PublicApiOriginGateTest
• Cover anonymous deny/allow per action, API key gating, origin allowlist, file content/transform 403 without read, item ?include= (files / relations / users), upload warm job, and focal cover.

# Use PHP 8.4 if your shell `php` is older (Herd):
php84 artisan test --filter=PublicCollectionApiTest
php84 artisan test --filter=PublicFilesApiTest
php84 artisan test --filter=PublicApiOriginGateTest

Source map

Related pages

• Public CMS API client types — TypeScript, OpenAPI 3, JSON Schema downloads
• Roles & permissions — editing roles and the Collection access matrix
• Effective permissions — admin Spatie model (separate from this API)
• Outbound webhooks — Externa → your URL (HMAC); not the same as API keys
• Collections API — session admin routes under /collections (not /api/v1)
• Routing overview — how api.php is registered
• Testing — Pest layout including Feature/Api

Field-level rules & item filters

collection_permissions.rules (JSON) on each Collection access grant (admin Roles UI → Fields & item filter):

{
  "fields": {
    "title": { "read": true, "create": true, "update": true },
    "status": { "read": true, "create": false, "update": false }
  },
  "item_filter": {
    "logic": "and",
    "rules": [{ "field": "status", "operator": "equals", "value": "published" }]
  }
}

Operators for item_filter: equals, not_equals, empty, not_empty (AND logic only). Applied for Public REST, GraphQL, and non–super-admin admin item access via CollectionPermissionGuard / CollectionPermissionRules.

Pest: tests/Feature/Api/CollectionPermissionRulesTest.php.

GraphQL (/api/graphql)

Dedicated guide: GraphQL.

Summary: Lighthouse endpoint at /api/graphql only (route name graphql; no /graphql app route). Same ResolveApiAccess + collection guards as REST. Queries: collections, collection(slug), items, item. Mutations: createItem, updateItem, deleteItem (soft-delete). Filter dialect matches REST/admin (perPage camelCase). Bruno: externa-bruno PublicApi/GraphQL/. Pest: tests/Feature/Api/GraphqlCollectionApiTest.php.

M2M junction metadata

Many-to-many values are objects (breaking change from bare ints):

{ "related_item_id": 12, "meta": { "sort": 1 } }

Bare ints are still accepted on write and normalized to { related_item_id, meta: {} }. Optional settings.junction_fields on the field defines the meta mini-schema (admin field settings → Junction fields JSON). See Field types and Collection items.

Advanced list filters

Same dialect as admin items index / GraphQL filter arg — see Collections API. Example: ?filter[status][_eq]=published. Bruno: externa-bruno List Items Advanced Filter.

System-column filters (core 1.4.0)

From #333, REST and GraphQL item lists also filter on the item's own columns:

?filter[published_at][_gte]=2026-01-01&filter[id][_in]=1,2,3

A system key wins over a collection field with the same name. An unsupported operator or a non-ISO value returns 422.

Relational filters (depth 1, core 1.4.0)

From #124, filter on a field of a related item with a dotted key relationField.relatedField:

?filter[author.name][_eq]=Ada
?filter[tags.slug][_in]=news,tech

• Works on many-to-one, one-to-many, and many-to-many relation fields, on SQLite, MySQL/MariaDB, and PostgreSQL (#436). Multi-relations match exact related ids and check every linked item.
• Depth is capped at 1: a.b.c returns 422 (Relational filter depth may not exceed 1).
• The related collection must be readable by the caller (same gate as ?include=), and the role's item filter on the related collection applies. An unreadable related collection matches nothing instead of leaking values.
• Unknown relation or related field names are ignored, like unknown plain field names.
• Each dotted key adds API_COST_FILTER_RELATION (default 2) to the request cost when the cost budget is on — API abuse controls.

Sort (core 1.4.0)

From #224, REST ?sort= takes up to 3 comma-separated keys; - means descending:

?sort=-published_at,title

Nulls sort last, ties break on id descending, and the default (no sort) stays id descending. Invalid tokens, unknown fields, non-sortable fields, fields hidden by field rules, or more than 3 keys return 422. GraphQL takes the same keys as sort: [String!]. Item payloads now include published_at, and new indexes on (collection_id, published_at | created_at | updated_at) back these sorts.