Inspiration API

Contract v2.6.1 — frozen. Breaking changes require a version bump and a parallel endpoint.

The API surface that creates and manages Inspirations — the static-asset entities you drop onto the grid: decks, docs, demo HTML, images. This is the single source of truth for any client that writes Inspirations: the web UI, the CLI (grid plug), and API automation.

1. Naming and verb

The user-facing verb is drop. The user-facing noun is Inspiration. The endpoints reflect this:

• POST /api/v2/inspirations — creates an Inspiration (the act of dropping)
• GET /api/v2/inspirations/:id — reads an Inspiration
• POST /api/v2/entities/:id/reactions — leaves a reaction (works on any entity)

The CLI command is grid plug <path> — plug is the unified verb for putting any node on the grid.

2. Auth

All endpoints require:

• Header: Authorization: Bearer <jwt>
• The JWT must resolve to a user with an active membership in the grid the request scopes to.
• Active grid context is determined by the X-CloudGrid-Grid header (the legacy X-CloudGrid-Org header is still accepted as an alias; when both are sent, X-CloudGrid-Grid wins). Required on all writes; defaults to your primary grid on reads if omitted.

If the header resolves to a grid you have no membership in, the response is 403.

3. POST /api/v2/inspirations — create

Request is multipart/form-data:

Scope and visibility — interaction rules

• scope: personal + visibility: private — only the owner can see it
• scope: personal + visibility: org — visible to all grid members at the owner's user-pathed URL
• scope: personal + visibility: link — anyone with the URL can see it (logged in or not)
• scope: space + visibility: space — visible to space members only
• scope: space + visibility: org — visible to all grid members but pathed under the space
• scope: org + visibility: org — visible to all grid members at the grid-pathed URL
• scope: org + visibility: private — invalid (returns 400)
• scope: org + visibility: space — invalid (no specific space defined)

Supported source_type values

The server validates the extension matches the declared source_type. Mismatch returns 415.

Response — 201 Created

{
  "entity_id": "7f8e2a4c-...",
  "name": "q2-pricing-deck-f8a2",
  "display_name": "Q2 Pricing Deck",
  "realm": "inspiration",
  "kind": "inspiration",
  "url": "https://acme.cloudgrid.io/q2-pricing-deck-f8a2",
  "scope": "personal",
  "space_id": null,
  "visibility": "org",
  "expires_at": "2026-05-13T00:00:00Z",
  "pinned": false,
  "source_type": "pptx",
  "status": "provisioning",
  "view_count": 0,
  "reactions": { "sparked": 0, "useful": 0, "build_on": 0, "impressive": 0, "discuss": 0 },
  "owner": { "user_id": "a1b2c3d4-...", "name": "Marcus Chen", "slug": "marcus" },
  "grid_slug": "acme",
  "space": null,
  "inspired_by": [],
  "created_at": "2026-04-13T14:22:31Z",
  "brain_status": "pending",
  "caller_permissions": { "can_edit": true, "can_archive": true, "can_pin": true }
}

The reactions map may also carry historical keys (viewed, resonated, love) as read-only pass-throughs alongside the five pressable kinds — no key ever disappears from the wire shape, so don't reject unknown reaction keys. See Reactions.

caller_permissions is server-computed: what you may do on this Inspiration (can_edit / can_archive / can_pin are true for the owner and grid admins). Use these flags to render action controls rather than re-implementing the check. They are also present on list rows.

When scope: space, the space field is populated with { space_id, slug, name }.

Status semantics

• provisioning — entity persisted, upload in progress, URL not yet serving
• live — URL serving content
• failed — provisioning failed; see the error in the entity detail
• archived — soft-deleted by owner or admin. Still readable by callers with visibility; reactions are refused.

Display the URL immediately on 201 but expect a brief 503 window. Poll GET /api/v2/inspirations/:id at 1-second intervals if you want to confirm live before showing an "Open" control.

brain_status semantics

• pending — enrichment queued
• enriched — description, icon, category populated
• skipped — enrichment failed; the Inspiration is fully usable, it just lacks auto-generated metadata

Enrichment is fire-and-forget. The upload response does not block on it.

4. GET /api/v2/inspirations/:id — read

:id accepts either an entity_id (UUID) or a name (slug), resolved against your active grid. Anonymous callers can only look up by UUID; a name-shaped param from an anonymous caller returns the same 404 NOT_FOUND shape as an unknown id, so the endpoint does not leak whether a slug exists.

Access

You must have read access per the Inspiration's visibility. The four modes:

• private — only the owner (and grid admins)
• authenticated — any signed-in caller, including cross-grid
• grid — scoped by visibility_spaces. Whole-grid (absent / empty / ['everyone']) means any member of the Inspiration's grid. A custom space subset means members of any listed space.
• link — anyone with the URL (no auth required, but a JWT enables view-counter dedup)

Response

Same shape as the create response, with current values, plus:

• description, icon, category, tags — enrichment output. Sparse: each field is present only when populated.
• visibility_spaces, link_indexed — the visibility sub-state. Sparse: visibility_spaces for grid, link_indexed for link. See Visibility.

Side effects

Calling this endpoint as an authenticated user counts as a view for that user (deduplicated by user-day). Anonymous calls (link visibility, no JWT) increment the counter using IP-day deduplication.

5. List endpoints

GET /api/v2/inspirations

Returns Inspirations visible to you. Visibility filtering is applied server-side — an Inspiration you cannot see is never returned, regardless of query parameters. Responses only include Inspirations in your active grid.

Response is { items, next_cursor, total_returned }. Each item is a summary row: entity_id, name, display_name, url, visibility, view_count, reactions, owner, sparse enrichment fields, created_at, caller_permissions, and three retention fields:

• status — the effective serving state. A published Inspiration that is serving, unexpired, and unarchived reads live; one past its expires_at reads expired; archived wins over both. Any other stored status passes through as-is.
• expires_at — the expiry instant; null when pinned / never-expiring.
• expires_in_days — whole days until expiry, clamped to 0 once passed. null means no expiry; 0 means already expired. 0 never means "no expiry".

The summary omits inspired_by — call GET /api/v2/inspirations/:id when you need the full shape.

GET /api/v2/runtimes

Returns Runtimes (Apps and Agents) visible to you. Runtimes are always grid-scoped; every runtime in your active grid is visible to every member.

Each item carries entity_id, name, display_name, kind, url, status, owner, sparse enrichment fields, created_at, updated_at. A never-deployed draft additionally carries sparse expires_at + expires_in_days (drafts expire after a platform-set TTL, 14 days by default); live, paused, and failed entities carry no retention clock.

6. PATCH /api/v2/inspirations/:id — update

Only the owner or a grid admin can update. Non-owner non-admin gets 403; cross-grid gets 404.

Request body (all fields optional; pass at least one):

Side effects of a scope change:

• * → space: space_id is set (required); membership verified
• space → *: space_id is cleared
• Uniqueness re-check at the new scope — 409 NAME_COLLISION if the slug already exists there
• The URL slug never changes — entity.name stays stable across PATCH. Rename would break the public URL.

Response: 200 with the refreshed full Inspiration shape, including caller_permissions.

7. Visibility

Every entity — Inspiration or Runtime — carries one of four visibility modes. Two modes carry a sub-state:

Read responses carry two sparse fields, each emitted only for the mode it belongs to: visibility_spaces (for grid, default ['everyone']) and link_indexed (for link, default false).

PATCH /api/v2/entities/:id/visibility

The write surface for the visibility model on any entity. :id accepts an entity_id (UUID) or a name/slug scoped to your active grid. You must own the entity or be a grid admin; otherwise 403 NOT_OWNER. Cross-grid access surfaces as 404.

Supplying visibility_spaces for a non-grid mode, or link_indexed for a non-link mode, returns 400 VALIDATION_FAILED. Each mode clears the sub-state it does not own, so a transition between modes never leaves stale fields behind.

For runtime entities, a visibility change re-applies the entity's Ingress so the serving auth posture (gated vs public) tracks the new visibility. Inspirations are enforced at the serving read path, so there is no re-apply step.

Response — 200: { entity_id, name, visibility, visibility_spaces?, link_indexed?, updated_at }.

PATCH /api/v2/inspirations/:id/visibility

The Inspiration parallel of the entity route, so clients carry one visibility shape across both realms. Same body, same validation, same response shape. One difference: this route still accepts legacy visibility values (org, space, link-anonymous, link-indexed, public) for a transition window and maps them to the four-mode model on store. A legacy value combined with either sub-state field is rejected — use the canonical mode.

This route writes visibility only. It never touches scope or the scope-owned space_id — scope is where the Inspiration lives; visibility is who can see it.

8. Errors

All errors follow one shape:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Some fields were not accepted.",
    "details": [
      { "field": "name", "issue": "already_exists", "hint": "Try 'q2-pricing-deck-v2'." }
    ],
    "request_id": "req_..."
  }
}

9. POST /api/v2/entities/:id/reactions — toggle a reaction

Leave or toggle a reaction on any entity you can read — app, agent, or Inspiration. (POST /api/v2/inspirations/:id/reactions is a deprecated alias with the identical shape; new clients use the entities path.)

{ "kind": "sparked" }

kind must be one of the five pressable kinds: sparked | useful | build_on | impressive | discuss. Three historical kinds (viewed, resonated, love) are retired as pressable and return 400 VALIDATION_FAILED on a press — their historical counts are preserved and still surface in reactions. Page views are counted by the visit beacon, not a reaction press.

Response — 200 OK

{
  "entity_id": "7f8e2a4c-...",
  "reactions": { "viewed": 0, "resonated": 1, "love": 5, "sparked": 3, "useful": 2, "build_on": 0, "impressive": 4, "discuss": 0 },
  "user_reactions": ["sparked", "impressive"]
}

• reactions is the global aggregate. It is eventually consistent — within a sub-second window the count reflects your toggle; the synchronous response carries the last-known total, which may not yet include the toggle you just made.
• user_reactions is your own active reactions, read synchronously — authoritative (read-your-write). Trust user_reactions for the toggle state and reconcile the displayed total against the next read.

Toggle behavior

POSTing the same kind twice toggles it off. The reaction state is strongly consistent; the count is derived asynchronously, so it never makes the toggle decision wrong.

Auth

You must have read access to the entity. Anonymous reactions (link visibility, no JWT) are not supported — only logged-in users can react. Reactions on private Inspirations are refused (403), and reactions on archived entities are refused.

10. POST /api/v2/views/:entity_id — visit beacon

Records one visit to a shared serving URL. The served public page is cached and byte-identical for every viewer, so a recipient opening a shared link never calls the detail endpoint — this beacon is the cache-safe signal. A tiny inline snippet on the served page fires it once on first paint. It is a thin wrapper over the same per-day-deduplicated view counter the detail read uses — not a separate counter.

• Auth: none required — a shared-link recipient is anonymous, and the view is deduplicated on a one-way IP hash. When a Bearer token is sent, dedup switches to the user id.
• Response: always 202 Accepted, empty body. Counting happens after the response, so the beacon never blocks the page. A bogus id, a filtered request, or a counting failure all still return 202.
• Body: optional and reserved for future attribution; the shipped browser beacon sends no body.

Filtering (so the count means something)

• Crawlers, link-unfurlers, and naive HTTP clients are dropped server-side.
• Owner self-loads are not recorded — the owner viewing their own page does not inflate the count.
• A cg-no-count cookie opts a browser out of counting.
• Per-day dedup: a single viewer reloading the same day does not double-count.

11. Rate limits

Exceeding a limit returns 429 with a Retry-After header (seconds) and the specific limit hit in error.details.

12. Active grid context

All write endpoints require the X-CloudGrid-Grid header to specify which grid you are acting in. The value is the grid's slug (e.g. acme). The server resolves the slug and validates membership. If the slug is unknown or you have no membership, the response is 403 ORG_NOT_ACCESSIBLE. For reads, the header is optional and defaults to your primary grid.

13. The inspired_by relationship

When creating an Inspiration, you can pass inspired_by: [entity_id, ...] listing up to 10 other Inspirations that inspired this one. Each referenced id creates a link. You must have read access to each referenced source — you can only declare a source you can see; otherwise the request fails with INSPIRED_BY_INVALID.

Links are realm-agnostic: a Runtime can be inspired by an Inspiration, and an Inspiration can build on another Inspiration.

Link endpoints

• POST /api/v2/runtimes/:id/inspirations — link a Runtime to an Inspiration source. Body: { "inspiration_entity_id": "<uuid>", "note": "<optional, up to 280 chars>" }. You need read access to both sides. Returns 201 with the new link row.
• DELETE /api/v2/runtimes/:id/inspirations/:link_id — remove a link. Caller must be the user who noted it, or a grid admin.
• GET /api/v2/runtimes/:id/inspirations — list Inspirations that inspired this Runtime. Sources you cannot see are silently omitted.
• GET /api/v2/inspirations/:id/inspired-runtimes — list Runtimes inspired by this Inspiration. Each row carries a linked_runtime summary; runtimes you cannot read are silently omitted.

14. What this contract does not cover

• Versioning or evolution UI
• Comments or threaded discussions
• Polls, scoring, or structured feedback
• Sharing notifications or invite-to-view flows
• Analytics beyond view count and reactions
• Runtime creation — separate contract
• Custom domain handling
• Pre-signed direct-to-storage uploads (uploads go through the API server)
• Bulk operations