---
title: "Content"
url: /patterns/content
---

# Content

> Sell access to what you publish, by subscription, by one-off purchase or by the read, to people and to their agents.

```text title="Issue: its lifecycle"
drafted ──review──▶ reviewed ──publish──▶ published ──send──▶ sent
```

| Access | [Price](/reference/platform.md#price) | What it opens |
| --- | --- | --- |
| Anyone | 0 | the list of Issues, each with its title and week |
| `Issue.read` | 0.25 a read | one whole Issue, for a person or an agent |
| Member | 8 a month | every Issue, and each edition by email |
| `Guide.buy` | 19 once | one Guide, kept for good |

Content is records sold by access. Newsletters, digital products and communities are three shapes of it: an edition on a schedule, a file bought once, and a space members post in.

```ts title="definition.ts"
import { define, generative } from 'apis.dev'

/** A weekly brief on the software companies that changed headcount, for members and their agents. */
export default define({
  name: 'briefs', domain: 'briefs.apis.dev',
  …
  sources: {
    firms: { api: 'companyfacts.apis.dev', cost: { 'Company.search': 0.005 } },
  },
  Issue: {                                              // an edition
    week: 'string!#', title: 'string', body: 'markdown',
    status: {
      draft:   { run: generative('This week in {firms}: who hired, who shrank') },
      review:  { in: 'drafted', role: 'editor' },      // a person reads every draft
      publish: { in: 'reviewed', role: 'editor' },
      send:    { in: 'published', to: 'Member' },       // a delivery send to every member
    },
  },
  Guide: { title: 'string', file: 'file' },             // a digital product
  on: { 'every Mon 06:00': 'Issue.draft', 'Issue.published': 'Issue.send' },
  offer: {
    'Issue.list': 0, 'Issue.read': 0.25,
    Member: { month: 8, includes: { 'Issue.read': 'all' } },
    'Guide.buy': { once: 19, grants: 'Guide.read' },
    terms: { license: { quote: 'with a link', train: false } },  // what a read allows
  },
})
```

`briefs` is built on [`companyfacts`](/patterns/dataset-api.md): its draft reads the week's changes as a [Source](/patterns/dataset-api.md#how-a-field-is-filled), and deploy prints its margin. A person reviews every draft before it can publish.

## Items, editions and access
| Family | What it does |
| --- | --- |
| Authored content | Posts, issues, pages and files, with drafts, versions, review and publishing, and full history |
| Editions | An Issue on a schedule, drafted by a person or an agent, published by a Role, sent once |
| Access tiers | Plans whose `includes` open whole items; anyone else sees what you leave open, and buys the rest |
| One-off products | A file or a bundle bought once, whose grant keeps it readable for good |
| Per-read sales | Any item priced by the read, so an agent with a budget buys the one Issue it needs |
| Communities | A space with posts and comments by members, under moderation |
| Licence terms | What a read allows, such as quoting with a link and no training, carried on every reply |

| Thing | States | What moves it |
| --- | --- | --- |
| An Issue | `drafted`, `reviewed`, `published`, `sent` | The schedule drafts it, an editor reviews and publishes it, and publishing sends it |
| A member's access | `trialing`, `active`, `past_due`, `cancelled` | Stripe's subscription; a cancelled member keeps access to the end of the paid period |
| A grant | `granted`, `refunded` | A one-off purchase, or its refund under the published rule |
| A post in a space | `posted`, `held`, `removed`, `restored` | A member posts; a flag or a rule holds it; a moderator removes or restores it, with a reason kept |

## Sending an edition
Publishing an Issue sends it to every member whose access is active, once, from your Domain. The send delivers what they bought, so it needs no separate consent. A member who turns email off still reads every Issue on the site and through the API.

Each send writes `Issue.sent`, and each member's delivery is kept with its state: `sent`, `delivered`, `bounced` or `opened`. A bounced address marks the member in the portal and stops further sends to it.

## Selling a read to an agent
An agent researching a company needs one Issue, not a subscription. It reads the list for free, then the Issue it wants, at the posted price per read.

```http title="GET /issues/2026-W44, with no credits"
HTTP/1.1 402 Payment Required
Content-Type: application/problem+json
X-Cost: price=0, currency="USD"
X-Request-Id: req_9b2d4e7a10c35f6e8d21

{
  "type": "https://briefs.apis.dev/docs/errors#payment_required",
  "title": "Payment Required",
  "status": 402,
  "detail": "The credit balance is 0; Issue.read draws 0.25 from it.",
  "code": "payment_required",
  "instance": "req_9b2d4e7a10c35f6e8d21",
  "offers": [
    { "kind": "verb", "name": "Issue.read", "price": 0.25,
      "checkout": "https://briefs.apis.dev/checkout/issue-read" },
    { "kind": "plan", "name": "Member", "price": 8,
      "checkout": "https://briefs.apis.dev/checkout/member" }
  ]
}
```

With credits, or paying inside the call under its mandate, the same request answers 200 with the whole Issue and `X-Cost: price=0.25`. The reply carries the licence terms, and the signed receipt names the Issue and its [Version](/reference/platform.md#version).

## Contracts and the platform's part
| You declare | The platform does |
| --- | --- |
| The content Nouns and their review and publish moves | Keeps drafts, versions and history; refuses a publish that skips its review |
| A schedule and a send | Drafts on the schedule, sends to every active member once, and keeps each delivery's state |
| Plans, per-read prices and one-off purchases | Opens or closes each item on every [Interface](/every-product.md), sells the rest through Checkout and the 402, and grants for good what was bought once |
| `terms` in the Offer | Carries them on every reply and receipt, and records each read against them |
| A space and its rules | Holds, removes and restores posts, and keeps the moderation record |

| Subsystem | What Content takes from it |
| --- | --- |
| Definition and compile | The review move a publish needs, checked at deploy, and the margin over each Source's `cost` |
| Model and records | Authored content, files, versions, search and the space's posts |
| Identity, access and policy | Members, tiers, editor and moderator Roles, and the one decision on every read |
| Data and Sources | What the draft reads, and what you import from where you published before |
| Runtime | Schedules, the send, and Events for every publish, read and delivery |
| Work | Review of each draft, and moderation of each held post |
| Commerce | Subscriptions, per-read prices, one-off grants and refunds, on Stripe |
| Interfaces and distribution | Delivery sends, the site's public pages, directory entries and the offer card |
| Trust and operations | Licence terms on every read, and the moderation record |

## What members and their agents meet
A reader finds the list of Issues, reads one whole Issue for 0.25, or joins as a Member and gets each edition by email. A member manages the plan, the email preference and the receipts in the portal.

An agent finishes the same path with no UI:

1. It lists Issues with `listIssues`, at no charge, and searches them by title.
2. It reads one Issue with `readIssue`, paying 0.25 within its `Max-Cost` and mandate.
3. It quotes from the Issue under the terms the reply carries, with the link.
4. It keeps the signed receipt, which proves what it read and what that read allowed.