Overview

The Content API turns a written brief and whatever source material you hand it into a finished, published piece of communication: a blog post, a one-page site, or a presentation deck. It is the public front door to the generation pipeline Jetski Bay runs internally — the same code path, reached with an API key instead of a browser session.

The base URL is https://content.jetskibay.com. Every request and every response is application/json, UTF-8. The version lives in the path: everything below is under /v1.

Responses are additive: a future release may add fields, and a well-behaved client ignores the ones it does not recognise. GET /v1 is the authoritative description of what this deployment currently supports — if this page and that response ever disagree, believe the API.

Authentication

Every metered endpoint takes a key, in either of two headers. Pick one; they are equivalent.

x-api-key: jbk_7c41f0a9d2e8b5163a0f4c7e

# …or, if your client prefers a standard scheme
Authorization: Bearer jbk_7c41f0a9d2e8b5163a0f4c7e

A request with no usable credential is rejected with 401 and carries the challenge header www-authenticate: Bearer realm="Jetski Bay Content API". Three endpoints need no key at all — GET /v1, GET /v1/variants and GET /v1/skills?variant=… — so you can build a picker in your own UI before anyone has signed up. /v1/skills is the one of the three that will not answer bare: its variant query parameter is required.

Every path here serves a fixed set of methods — the three create endpoints are POST only, everything else is GET, plus DELETE on /v1/keys/current. Anything else on a path that does exist is 405 method_not_allowed, not a 404. And a deployment with no key-signing secret configured answers 503 key_secret_unavailable on every keyed route before it looks at your credential at all — that one is ours to fix, not yours.

Keys

Keys are minted per email address and mailed to it. A trial key is good for 10 requests and expires 24 hours after it is issued. Only a hash of the key is stored, so the email is the one place the key itself exists: if you lose it, mint another.

POST/v1/keys

Mints a key for an email address and mails it. No authentication — this is how you get authenticated in the first place. The response never contains the key.

curl -X POST https://content.jetskibay.com/v1/keys \
  -H "content-type: application/json" \
  -d '{"email":"you@company.com"}'

{
  "status": "sent",
  "message": "Your API key is on its way to you@company.com.",
  "key": {
    "keyPrefix": "jbk_7c41f0a…",
    "tier": "trial",
    "requestLimit": 10,
    "requestsRemaining": 10,
    "expiresAt": "2026-09-06T09:12:44.000Z"
  }
}

The job contract

All three create endpoints behave identically. You POST a brief, you get 202 immediately, and you poll the URL it hands you until the job reaches a terminal state.

{
  "requestId": "9c2f7a41-6d0b-4f18-9a72-1b3e5c8d40aa",
  "status": "queued",
  "variant": "blog",
  "statusUrl": "https://content.jetskibay.com/v1/jobs/9c2f7a41-…",
  "pollAfterMs": 4000,
  "contextRef": "contexts/4f0b…c71a/manifest.json"
}

Wait pollAfterMs milliseconds, then GET the statusUrl. Keep waiting and polling while status is queued or running. Do not invent your own interval that is shorter than the one you were given — the number is there so we can slow you down without breaking you.

The first five are the whole set. Treat anything else — including unknown — as "still working" and keep polling until the response says otherwise.

A terminal succeeded carries a result object: entityId always, liveUrl for a blog post or a page, downloadUrl for a deck. A terminal failed or cancelled carries error instead. Only a non-terminal response carries pollAfterMs, so its absence is itself a signal that the job has stopped moving.

A create also honours an idempotency-key request header — one to 180 visible characters. Send the same key twice with the same body and the prepared context is reused rather than rebuilt, and the key travels on to the pipeline so a retry does not fan out into parallel work. Send the same key with a different body and the request is refused with 409 invalid_request. Omit it and one is generated for you, which means a blind retry is a fresh run. Note that the header does not make a retry free: quota is charged per request, before any of this is looked at.

A running job also reports the pipeline phase it is in, in this order: prepare, source, generate, validate, commit, publish. Phases are for showing a human what is happening; branch on status, not on phase.

Service index

GET/v1

Unauthenticated. Reports the API version, the variant list, the current trial terms, the list of endpoints this deployment serves, and the branding state of each generator. If you are writing a client, read this rather than hardcoding what this page says.

{
  "service": "jetskibay-content",
  "version": "v1",
  "schemaVersion": 1,
  "documentation": "https://content.jetskibay.com/docs",
  "variants": ["blog", "page", "deck"],
  "trial": {
    "requestLimit": 10,
    "windowHours": 24,
    "deliver": "email"
  },
  "endpoints": {
    "index": "/v1",
    "variants": "/v1/variants",
    "skills": "/v1/skills",
    "keys": "/v1/keys",
    "keyStatus": "/v1/keys/current",
    "posts": "/v1/posts",
    "pages": "/v1/pages",
    "decks": "/v1/decks",
    "jobs": "/v1/jobs/{requestId}",
    "deckDownload": "/v1/decks/{id}/download"
  },
  "brandSource": {
    "blog": "live",
    "page": "live",
    "deck": "unreported"
  }
}

brandSource

Each generator resolves the Jetski Bay brand live at run time and falls back to a compiled-in snapshot when that fetch fails. Somebody working in the Show UI can see a degraded brand on the page in front of them. You cannot: you get a finished artifact with no way to tell which branding went into it. That asymmetry is the only reason this field is here.

The whole index response is cached for 60 seconds, because it takes no key and three health probes per anonymous hit would be an amplifier rather than a feature. So brandSource is up to a minute stale, and it is not a monitoring endpoint — status.jetskibay.com is.

Variants

GET/v1/variants

Unauthenticated. Returns the three variants — blog, page, deck — with the modes each one accepts, the options each one honours, where its output lands, and the endpoint each one is posted to. This is the honest source for a variant picker: if we add options or change a mode, they show up here first.

{
  "variants": [
    {
      "id": "deck",
      "label": "Presentation deck",
      "endpoint": "/v1/decks",
      "modes": ["create", "rewrite"],
      "output": {
        "kind": "download",
        "downloadEndpoint": "/v1/decks/{id}/download",
        "liveUrl": false
      },
      "options": {
        "targetSlides": { "type": "integer", "minimum": 3, "maximum": 30 },
        "aspectRatio": { "enum": ["16:9", "4:3"] },
        "speakerNotes": { "type": "boolean" },
        "audience": { "enum": ["general", "leadership", "project-team", "external"] },
        "tone": { "enum": ["insightful", "direct", "optimistic"] },
        "goal": { "enum": ["inform", "align", "persuade", "launch"] },
        "density": { "enum": ["airy", "balanced", "detailed"] }
      }
    }
  ]
}

output.kind is "published" with liveUrl: true for blog and page, and "download" with liveUrl: false for deck. Branch on that rather than hardcoding the one exception.

Modes are per variant

There is no universal set of modes. page takes create and update; blog and deck take create and rewrite. Sending a mode a variant does not accept is a 400 invalid_request naming the variant — not a silent downgrade to create.

The modes array on this endpoint is the authoritative list — the table above is a convenience, and if the two ever disagree, believe the API. mode defaults to create when you omit it. update and rewrite both require an entityId, and that id must be one a finished job of yours produced.

Skills

GET/v1/skills?variant=blog

Unauthenticated. A skill is a named behaviour the pipeline can switch on for a run — a house style, a research habit, a structural pattern. Pass variant to get the catalogue that applies to that variant, then send the ids you want as skillIds on the request body.

Every variant already runs three skills you did not ask for — the ones marked selected_by_default, which are also the ones marked required. Those count against the ceiling of five skills per run, so in practice you are adding at most two. Ask for a sixth, or for an id that is not in this variant's catalogue, and the request comes back 400 bad_request saying which.

{
  "variant": "blog",
  "skills": [
    {
      "id": "…",
      "label": "…",
      "description": "What this skill changes about the run.",
      "variants": ["blog"],
      "required": false,
      "selected_by_default": false,
      "version": "…"
    }
  ]
}

Skill ids are not stable literals in this document on purpose — the catalogue moves. Read it at request time and send back ids you got from it.

Create

Three endpoints, one body. The variant is the path you post to, so you do not send a variant field.

All three answer 202 with the job envelope described in the job contract. All three charge one request against your key at the moment work starts.

curl -X POST https://content.jetskibay.com/v1/posts \
  -H "x-api-key: $JETSKI_KEY" \
  -H "content-type: application/json" \
  -d '{
    "mode": "create",
    "brief": "How we cut cold-start latency on the fleet. Lead with the
              measurement, not the fix. Engineers, not executives.",
    "research": { "webSearch": true },
    "options": {
      "targetWords": 900,
      "audience": "project-team",
      "tone": "direct",
      "goal": "inform"
    }
  }'

# Updating an existing one-pager in place: pass its entityId.
curl -X POST https://content.jetskibay.com/v1/pages \
  -H "x-api-key: $JETSKI_KEY" \
  -H "content-type: application/json" \
  -d '{
    "mode": "update",
    "entityId": "pg_4f81c07a",
    "brief": "Refresh the numbers for Q3 and drop the pilot section.",
    "options": { "audience": "external", "density": "airy" }
  }'

curl -X POST https://content.jetskibay.com/v1/decks \
  -H "x-api-key: $JETSKI_KEY" \
  -H "content-type: application/json" \
  -d '{
    "brief": "Fifteen minutes on the migration, for the leadership review.",
    "research": {
      "webSearch": false,
      "urlCaptures": [
        { "url": "https://example.com/postmortem",
          "includeText": true, "includeScreenshot": false }
      ]
    },
    "options": {
      "targetSlides": 12,
      "aspectRatio": "16:9",
      "speakerNotes": true,
      "audience": "leadership",
      "goal": "align"
    }
  }'

The page example says "mode": "update" because that is the follow-up mode a page has. The same shape against /v1/posts or /v1/decks would say "mode": "rewrite" instead — swapping the two is a 400, and one you have already paid for. See modes.

Poll a job

GET/v1/jobs/{requestId}

Free — polling never consumes quota. A job is readable by any key minted to the address that started it, which is not the same thing as the one key that started it: see keys for why re-minting has to keep working. A key belonging to a different address gets 404, not 403, because whether that job exists is none of its business.

{
  "requestId": "9c2f7a41-…",
  "variant": "blog",
  "status": "running",
  "phase": "generate",
  "createdAt": "2026-09-05T09:12:44.000Z",
  "updatedAt": "2026-09-05T09:14:02.000Z",
  "pollAfterMs": 4000
}

{
  "requestId": "9c2f7a41-…",
  "variant": "blog",
  "status": "succeeded",
  "phase": "publish",
  "result": {
    "entityId": "how-we-cut-cold-start-latency",
    "liveUrl": "https://blog.jetskibay.com/posts/how-we-cut-cold-start-latency"
  }
}

{
  "requestId": "3b70e2c9-…",
  "variant": "deck",
  "status": "succeeded",
  "phase": "publish",
  "result": {
    "entityId": "dk_1a9f0c",
    "downloadUrl": "https://content.jetskibay.com/v1/decks/dk_1a9f0c/download"
  }
}

A deck carries downloadUrl and no liveUrl; a blog post or a page carries liveUrl and no downloadUrl. Neither key is invented for the other variant, so result.liveUrl being absent on a deck is the contract, not a missing field.

{
  "requestId": "9c2f7a41-…",
  "status": "failed",
  "error": "The brief did not contain enough to write about."
}

Download a deck

GET/v1/decks/{id}/download

Returns the deck artifact for a finished deck job, authenticated with any key minted to the address that created it. This is the only way to get a deck out of the API — see where output lands for why. Free: the request that made the deck was already charged, and charging again for fetching the thing you paid for would make a retried download cost real money.

The {id} must be an entity one of your finished jobs produced — which, as the job contract says, means a job you polled through to succeeded. Anything else is 404: an id you never made, an id you made but never polled, and someone else's id are deliberately indistinguishable from the outside.

curl -L https://content.jetskibay.com/v1/decks/dk_1a9f0c/download \
  -H "x-api-key: $JETSKI_KEY" \
  -o deck.html

Key status

GET/v1/keys/current

Reports the allowance and expiry of the key on the request. Free — checking how much you have left does not spend any of it. Useful as a cheap credential check before you commit to a run.

{
  "key": {
    "keyPrefix": "jbk_7c41f0a…",
    "tier": "trial",
    "requestLimit": 10,
    "requestCount": 3,
    "requestsRemaining": 7,
    "createdAt": "2026-09-05T09:12:44.000Z",
    "expiresAt": "2026-09-06T09:12:44.000Z",
    "lastUsedAt": "2026-09-05T10:40:11.000Z"
  },
  "valid": true,
  "reason": ""
}

An expired or exhausted key still answers here — that is the point of the endpoint. valid goes false and reason carries the code you would have got from a real call (expired_api_key, quota_exhausted). Only a credential we cannot resolve at all is an error instead.

DELETE/v1/keys/current

Revokes the key on the request, immediately and permanently. Also free. Use it the moment a key ends up somewhere it should not be — in a screenshot, a commit, a support ticket. Revoking does not stop you minting another at the same address.

Revoking costs you nothing and buys you nothing. The allowance belongs to the address for a rolling 24 hours, not to whichever key happens to be alive: a new key is issued for the trial limit minus everything that address has already spent in the window, whether the key that spent it is live, revoked, or expired. So re-minting over a working key and revoking first come out at exactly the same number, and an address that has spent all ten gets 429 allowance_exhausted until the window rolls forward. Mint often enough and you will meet the per-address and per-network mint caps first, which are 429 mint_limit_reached for the rest of the day.

Request body

The three create endpoints share one body: the platform's generation contract, schema version 2. Everything is optional except brief.

The options block

Where output lands

Two of the three variants finish at a public address. One does not, and it is worth knowing which before you build a UI around it.

Errors

Every error, from every endpoint, is the same JSON shape: { "error": "…", "code": "…" }. The error string is written to be shown to a person. The code is the stable thing to branch on.

One code carries a third field. invalid_request is what a body the generation contract rejects comes back as, and it lists every problem it found in an issues array — all of them at once, so you are not fixing one field per round trip:

{
  "error": "The request body is not valid: mode rewrite is not valid for page; options.tone must be one of insightful, direct, optimistic.",
  "code": "invalid_request",
  "issues": [
    "mode rewrite is not valid for page",
    "options.tone must be one of insightful, direct, optimistic"
  ]
}

Every response, including every error, carries an x-request-id. It is the one thing worth logging on a failure and the one thing worth quoting to us.

Quota rules

A trial key is 10 requests over 24 hours. The rules for what counts are short, and they are worth reading once rather than discovering.

• A request is charged when work starts, not when it finishes. Posting a brief spends one, whether the result delights you or not.
• Refunds happen only when we 5xx. If the platform itself fails, the request goes back on your allowance automatically. Nothing to claim.
• Your own 4xx still costs a request once work has started. Validate the body before you send it.
• Polling is free, always. GET /v1/jobs/{id} costs nothing, no matter how many times you call it. So do GET /v1/keys/current and DELETE /v1/keys/current, and so do the three unauthenticated catalogue endpoints.
• Re-minting never tops you up. A new key carries the remainder of what its address has spent in the last 24 hours and revokes any predecessor — and revoking first changes nothing, because spend counts against the address whether or not the key that spent it still exists. Losing a key costs nothing; deleting one buys nothing.
• There is no remaining-quota response header. Nothing here emits one, and a browser client could not read one if it did: the only response headers exposed across origins are x-request-id and retry-after. Ask GET /v1/keys/current instead — it is free, it is authoritative, and polling it costs nothing.

Need more than a trial — real volume, a longer-lived key, your own vault projects? Say so at hello@jetskibay.com, or go and break the playground first.