BetterMarketer.ai
Sign InStart Free
The spec is publicNo key needed

Your marketing brain,
available to your own code

A versioned REST API and an MCP server. Everything the app does to a source — capture it, generate a structured note, read it back with its citations intact — your code can do too, and so can an agent working on your behalf.

Start Free

No credit card required.

  • REST
  • MCP
  • Jobs
  • Batches

The surface

One API, and the verbs are the product’s own

Capture a source, generate a note, poll the job, read it back — and run the whole thing in bulk. Every operation below is in the published spec, grouped by what you would reach for it to do.

  • Capture and generate

    A local media file, a YouTube URL, a web article or raw text goes in; a structured note comes back, with its table of contents, its sections and its citations. Upload first for local media, then name the returned path.

    • POST /uploads
    • POST /notes
    • GET /notes
    • GET /notes/{id}

  • Jobs, because generation takes time

    Creating a note enqueues work and hands you a job rather than holding a request open for minutes. Poll it until it completes, then read the note by id. The same endpoint polls Specialist jobs too — a type field tells the two apart — and DELETE cancels a pending Specialist job, which is the only kind that can be cancelled.

    • GET /jobs/{id}
    • DELETE /jobs/{id}

  • Bulk, without a queue of your own

    Point it at a playlist or a whole channel with an Idempotency-Key header and it hands back a batch id instead of holding a connection open; replaying the same key returns the batch you already started rather than charging twice. Poll it for status and the succeeded and failed counts until every note has landed.

    • POST /batches
    • GET /batches/{id}

  • Look before you fetch

    Enumerate a playlist or a channel and read a transcript, so your code can decide what is worth generating before it commits to generating anything.

    • GET /playlist-videos
    • GET /channel-videos
    • GET /transcript

  • Notebooks, and projects behind a gate

    Assemble a knowledge base from a script instead of by hand: create a notebook, then ingest sources straight into it. The project paths ship alongside them and are in the spec, but that surface is still gated — an account it has not been opened on gets a 404 — so read them as a preview rather than something to build on today.

    • POST /notebooks
    • GET /notebooks
    • POST /notebooks/{id}/ingest
    • POST /projects
    • GET /projects
    • GET /projects/{id}
    • POST /projects/{id}/sources

  • LinkedIn posts

    List the posts behind a profile URL or search posts by keyword — discovery saves nothing — then save the ones worth keeping as first-class, citable sources.

    • POST /linkedin/fetch
    • POST /linkedin/save

  • Specialists

    List the named agents on your account and ask one a question, synchronously, as a stream, or as a job you collect later.

    • GET /gpts
    • GET /gpts/{slug}
    • POST /gpts/{slug}/chat
    • POST /gpts/{slug}/chat/stream
    • POST /gpts/{slug}/chat/async

  • Your own keys

    Mint, list, inspect, amend and revoke keys. These five paths are the one exception to bearer authentication: they authenticate with your signed-in session and not with an API key, so no key can ever mint or widen another key.

    • GET /api-keys
    • POST /api-keys
    • GET /api-keys/{id}
    • PATCH /api-keys/{id}
    • DELETE /api-keys/{id}

A request, end to end

From a URL to a note in three calls

Nothing is hidden behind a client library. It is one POST, one poll and one read.

Request

POST /api/v1/notes
Authorization: Bearer <your API key>
Content-Type: application/json

{ "kind": "youtube", "url": "https://www.youtube.com/watch?v=..." }

Response

202 Accepted

{ "job_id": "...", "status": "...",
  "note_id": "...", "poll_url": "..." }

Poll the poll_url the response hands back — GET /jobs/{id} for a video, an upload or a brief — until it reports completed, then GET /notes/{id} for the note’s markdown and its metadata. kind is one of youtube, upload, text or web_article, so the same endpoint takes a video, a file you have already uploaded, a pasted brief or an article URL.

  • Authentication is a bearer API key in the Authorization header, minted from the dashboard on the Master plan, or issued through the OAuth connector.
  • Two paths need no key at all: a health check and the spec itself, so a tool — or an agent — can discover the surface before it has any credentials.

MCP

The same API, as tools an agent can call

One endpoint, POST /api/mcp, speaking JSON-RPC 2.0 in the stateless Streamable HTTP mode — no session to keep alive, no second dialect to learn.

  • Each tool re-invokes the matching REST route handler with the same credentials, so behaviour and per-tool permissions are identical to the REST surface. One implementation, not two that drift apart.
  • Claude, ChatGPT and Cursor connect to it directly. An unauthenticated request answers with the metadata a client needs to begin an OAuth flow, which is what lets those clients offer a one-click connect.
  • OAuth is standards-track: PKCE and dynamic client registration, scoped consent, and a connections list you can revoke from at any time.

Eighteen tools, and every one of them fronts a documented path

  • create_note
  • create_upload_url
  • get_note
  • list_notes
  • linkedin_fetch_posts
  • linkedin_save_post
  • get_job
  • get_transcript
  • list_playlist_videos
  • list_channel_videos
  • create_batch
  • get_batch
  • create_notebook
  • list_notebooks
  • create_project
  • list_projects
  • get_project
  • ingest_project

Keys and access

A key is a scoped credential, not a password

Every key is issued with the reach you choose and can be narrowed, expired or revoked without touching anything else.

  • Hashed at rest. Only a short prefix is kept for display, and the key itself is shown once, at creation.

  • Named, described and given an expiry, so a key you handed to one script is identifiable a year later.

  • A granular permission set per key: reading notes, creating notes, reading media, bulk fan-out, ingesting knowledge and talking to Specialists are separate switches.

  • A per-minute and a per-day rate limit on every key, checked on every authenticated call. The Specialists and job endpoints hand the limit and what is left of it back in X-RateLimit headers; everywhere else you meet one as an explicit 429, not as a dropped connection.

  • An optional IP allowlist, checked on every call.

  • Every call is audit-logged with a correlation ID, so a key’s history is answerable.

Good to know

What this API is, and what it is not

  • The machine-readable spec is public and needs no key. The human-readable reference lives inside the app, behind sign-in.

  • API keys are minted on the Master plan. The plans are on the pricing page.

  • The API returns the thinking and the deliverable. It does not write to an ad platform, a CMS or an ESP. We make the thinking defensible; you keep control of spend.

  • A note created through the API lands in the same library the app reads, categorised and connected the same way, and searchable the moment it lands.

  • Your content is not used to train AI models. Your uploads, chats and questions stay private.

See the plans
Developers

Create an account, mint a key, and point your code at it.

Nothing is hidden behind a client library. It is one POST, one poll and one read.

Start FreeOpen the OpenAPI spec

No credit card required.

Creating a note through the public API