This page is the human-readable reference for the
MaxGood.work Public BETA API (Phase 1). The
machine-readable OpenAPI 3 specification is linked at the bottom of
the page and is also embedded as the interactive endpoint reference
further down.

The Public BETA API gives Enterprise Avatar Owners and Avatar
Admins programmatic access to their Avatar — its content, its
chunks, and its ability to reply on behalf of a member. It is
intended for server-to-server integrations; the API
key is a long-lived secret and must never be embedded in browser,
mobile, or any other client-side code.

Before you start: the Stability & Use Contract

The full Stability & Use Contract is the
authoritative companion document to this reference. It covers what
MaxGood.work promises to keep stable, how breaking changes are
announced (with at least 1 week notice during BETA, on this page
and our Discord), what an Avatar API key actually grants (full
Avatar-admin access in Phase 1), how we handle your data, and how
to get help. Read it once before you build:

The contract is published in the
Stability & Use Contract
section at the bottom of this page.

Getting an API key

Sign in to MaxGoodWeb as the Avatar Owner or an Avatar Admin
of the Enterprise Avatar you want to integrate.
Open Avatar Admin > Account.
Create a new API key. Give it a recognizable label (e.g. the
name of the integration that will use it) so you can audit and
revoke it cleanly later.
Copy the raw token immediately. It looks like
mgak_<credential_id>.<secret> and is shown
only once at creation. We store a bcrypt hash; we cannot recover
the raw token. Treat it like a password.
Store the key in your integration’s secrets manager (AWS
Secrets Manager, GitHub Actions secrets, a `.env` file with
restricted permissions — whatever you already use). Do not commit
it to source control.

You can revoke a key at any time from the same tab. Revocation
is immediate; subsequent calls with a revoked key receive
HTTP 401.

Making a request

All requests authenticate with the API key in the
Authorization header:

Authorization: Bearer mgak_<credential_id>.<secret>

The base URL is:

https://api.maxgood.work/v1beta

A minimal worked example — confirm your credentials are wired
up by fetching the Avatar identity:

curl -s https://api.maxgood.work/v1beta/organization \
  -H "Authorization: Bearer mgak_<credential_id>.<secret>"
# {"response":{"org_id":"<your-org-id>"},"result":"success"}

Every successful response is wrapped in a
{"result": "success", "response": …} envelope, and
every failure is {"result": "failure", "response": "…"}
with a human-readable message. (The few endpoints that return raw
content — for example the chunk-preview endpoint, which returns
text/plain — note this in their per-endpoint
documentation below.)

What’s in scope (Phase 1)

Enterprise — Avatar identity, semantic
retrieval, and tagging.
Content management — titles (create / read /
update / delete / enable), per-title documents, chunks (read /
preview / edit / delete), title footers.
Avatar reply — get the Avatar’s response to a
message on behalf of a named member of the Avatar.
Users — list Avatar members, invite new
members (or attach existing MaxGood.work users to the Avatar),
edit per-Avatar membership flags / notes / license expiry, and
soft-remove a user from the Avatar without affecting other
Avatars they belong to.

Avatar-side newsjacking generation is NOT in Phase 1; it will be
added shortly. Phase 2 will not change the Phase 1 surface.

The Users surface has three rules integrators
must understand:

No-overwrite of user identity. If the email
on a POST /users matches an existing MaxGood.work
user, that user’s identity fields (name, role, expertise,
industry, goal, problem, language) are silently preserved. Only
the per-Avatar membership is added. The response carries
existing_user=true.
PUT is per-Avatar only. User identity is
set on POST and is not editable via
PUT /users/{user_id}. Sending a user-level field
returns 400. is_owner is also not
acceptable on this endpoint (owner transfer is a staff-side
operation).
POST quotas. Three ceilings apply in order:
a per-Avatar invite rate limit of 200 invites per rolling hour
(429 with Retry-After), the legacy
org-type user_limit ceiling (403), and a
security/abuse cap of 1000 active members per Avatar
(403 with a contact-support message; lift-able
per-Avatar by MaxGood.work support).

Endpoint reference

The interactive reference below is rendered from the published
OpenAPI 3 specification. You can also
download the raw specification
and generate clients with the tools of your choice.

Stability & Use Contract

Phase 1, BETA · Effective 2026-05-20 (initial
publication)

The contract that follows is the canonical version. The
authoritative source lives in version control at
docs/PUBLIC_BETA_API_CONTRACT.md in the MaxGoodAI
repository; every commit to that file is a versioned policy
change.

MaxGood.work Public BETA API — Stability & Use Contract

Phase 1, BETA · Effective 2026-05-20 (initial publication) Authoritative source: docs/PUBLIC_BETA_API_CONTRACT.md in the MaxGoodAI repository

This document sets out the commitments MaxGood.work makes to integrators using the Public BETA API, and the expectations we place on those integrators in return. It covers what we promise to keep stable, how we will communicate changes, how the API is authenticated, what is in scope, and how to get help.

The Public BETA API is published at endpoints under the /v1beta/ URL prefix on the MaxGood.work backend (https://api.maxgood.work/v1beta/... in production). The OpenAPI specification and per-endpoint reference live at https://blog.maxgood.work/api-documentation-beta and this contract is linked from there.

1. Who can use it

The Public BETA API is for Enterprise Avatar Owners and Avatar Admins. Avatar Admins create an API key from the MaxGoodWeb Avatar Admin > Account tab. Each key is bound to exactly one Avatar; calls authenticated with that key act only on, and only on behalf of, that Avatar. If you administer more than one Avatar, each Avatar needs a separate API key.

The BETA API is intended for server-to-server integrations. Do not embed an API key in a browser, mobile app, or any client-side code: the key is a long-lived secret and any client-side use exposes it. There is intentionally no browser-friendly CORS configuration on /v1beta/*.

2. The BETA label — what it means

“BETA” is a real and substantive designation:

The API is functional and ready to use for integrations. We use it in production and ship customer features over it.
The contract surface is not yet General Availability (GA). We may evolve endpoints during BETA, including occasional breaking changes, while we observe how integrators actually use it.
Every breaking change during BETA is announced with at least 1 week notice on the documentation page, and on our Discord server. We do not announce changes to any other destination during our BETA. See §6 — Deprecation policy below.

When the API exits BETA, it will be re-published under /v1/ with a longer GA stability commitment, additional announcement destinations, and /v1beta/ will remain available for the announced sunset period before retirement (typically 1 week).

3. Authentication and what an API key grants

Authentication uses the org API key in the Authorization header:

Authorization: Bearer mgak_<credential_id>.<secret>

Keys are bcrypt-hashed at rest; the raw token is displayed only once, at creation. Treat it as a password.

An Avatar API key is a full-Avatar-admin credential. It grants the complete BETA surface for the Avatar it is bound to: reading content, creating/updating/deleting content, managing members/clients, and generating Avatar responses on behalf of members/clients. There is no per-key read/write/delete scoping in Phase 1; an API-key holder is, for the purposes of the BETA, an Avatar Admin acting on the Avatar. Issue keys accordingly. (Per-key scoping is on the roadmap and may arrive in a later phase or at GA; when it lands it will be additive and backwards-compatible.)

Keys can be revoked at any time from the same MaxGoodWeb tab. Revocation is immediate; subsequent calls with a revoked key receive HTTP 401.

Exception — the public read tier. The endpoints under /v1beta/public/* (see §4 → “Public read tier”) require NO API key at all; they expose only already-public marketing data and are rate-limited per client IP instead. Everything else in this contract requires the API key described above.

4. What’s in scope (Phase 1 BETA)

The Phase 1 BETA surface, all under /v1beta/:

Enterprise

GET /organization — the caller’s Avatar identity
POST /rag-search — semantic retrieval over the Avatar’s content
POST /tags — add tags to a member

Content management (Avatar-scoped)

GET /content/titles, POST /content/titles
GET /content/titles/{id}, PUT /content/titles/{id}, DELETE /content/titles/{id}
GET /content/titles/{id}/state, PUT /content/titles/{id}/enabled
POST /content/titles/{id}/upload, GET /content/titles/{id}/documents
GET /content/titles/{id}/chunks, GET /content/titles/{id}/footer
POST /content/footers
GET /content/chunks/{id}, PUT /content/chunks/{id}, DELETE /content/chunks/{id}
GET /content/chunks/{id}/preview

Get a response from an Avatar

POST /avatar/respond — a chat reply on behalf of a named member of the Avatar

User management (Avatar-scoped)

GET /users — list the Avatar’s active members (paginated, page_size clamped at 200)
POST /users — invite a user into the Avatar
GET /users/{user_id} — read one user’s identity + this Avatar’s membership
PUT /users/{user_id} — update this Avatar’s per-membership fields
DELETE /users/{user_id} — soft-remove the user from this Avatar (cross-Avatar invariant preserved)

The user-management surface follows three special rules that integrators MUST understand:

No-overwrite of user identity on POST. When the email matches an existing MaxGood.work user, that user’s identity fields (name, role, expertise, industry, goal, problem, language) are silently preserved. Per-Avatar fields (is_admin, is_coach, license_expiry_date, notes, structured_data) ARE applied to the new membership. The response indicates existing_user=true so the integrator can detect the case.
PUT is per-Avatar only. User identity is not editable via PUT /users/{user_id} — that surface manages only this Avatar’s relationship to the user. Sending a user-level field (e.g. name) returns 400. is_owner is also not acceptable on this endpoint (owner transfer is a staff-side operation).
POST quotas. Three checks apply, in order: a per-Avatar rate limit of 200 invites per rolling hour (429 with Retry-After), the legacy org-type user_limit ceiling (403), and a security/abuse cap of 1000 active members per Avatar (403 with a contact-support message; lift-able per-Avatar by MaxGood.work support).

Avatar-side newsjacking generation is not in Phase 1; it will be added shortly. Phase 2 will not change the Phase 1 surface.

Public read tier (no authentication) — Phase 3

A distinct tier of endpoints lives under /v1beta/public/*. Unlike every other endpoint in this contract, these require NO API key. They expose only data that is already published on the MaxGood.work marketing site, so there is nothing Avatar-scoped to protect:

GET /v1beta/public/avatars — publicly-listed Avatars: every Avatar whose public listing state is on and whose Avatar type has a public listing category. Curated public-safe fields only (prompt, integration settings, email domains and internal ids are never exposed); member and waitlist counts are never published — each Avatar carries a popularity label (NEW, POPULAR or WAITLIST) instead. Each Avatar also carries its listing category (key, label, rank; always set), avatar_info_url (an http(s) address, or empty when the Avatar has none), created_on, has_icon, a public_link (its newest intake form open to the public without an access code, else its info URL) and public_sort_rank (equal to category.rank; lowest first). Items are ordered by Avatar id; clients apply their own display ordering. Optional exact ?type= filter (e.g. Author Avatar). The response is not cached.
GET /v1beta/public/free-avatars — the Avatars a new MaxGood.work account receives for free: one entry per Avatar, ordered by name, each carrying ONLY name, free_trial_days (0 = free with no end date; otherwise the free period in days) and key_benefit (one short sentence naming the Avatar’s key benefit; empty when none has been written). No ids, emails or other fields. Cached for up to 5 minutes.
GET /v1beta/public/foundation-titles — public Foundation Titles (positive weight tier, not deleted) with their description and a live usage count. The weight tier itself is not exposed.
GET /v1beta/public/showcase — the licensed-expert showcase composed for display: the public Foundation Titles (one entry per title, ordered by name, with the author names to print already resolved) and the publicly-listed Author Avatars (the GET /v1beta/public/avatars listing narrowed to Author Avatar; each with a blurb composed from its five public Align fields).
GET /v1beta/public/authors — the public Licensed Author directory (authors who own a public Author Avatar or have ≥1 public Foundation Title); public-safe profile fields only (display name, bio, backlink, approved-only photo URL).
GET /v1beta/public/stats — platform-wide historical totals (organizations, users, interactions). These intentionally include archived/soft-deleted rows, so they are historical totals rather than current-exact counts.

Because there is no API key, abuse on this tier is bounded by a per-client-IP rate limit (returns 429 with Retry-After); CORS is open. These endpoints are read-only and safe to call from a browser. They obey the same {result, response} envelope and the same stability/deprecation commitments (§5, §6) as the rest of the surface.

5. Stability promise

For every endpoint listed in §4 we commit to not change the following without going through the deprecation process in §6:

The URL path and HTTP method.
The set of required request fields and their meaning.
The semantic meaning and type of each response field that is already documented.
The set of error status codes that are part of the published behaviour.

We may make changes that are backwards-compatible at any time, without prior notice:

Add new endpoints under /v1beta/.
Add new optional request fields.
Add new fields to the response object (an integrator’s parser must tolerate unknown fields).
Improve error-message text (the structured result / response shape stays).
Improve performance, retries, and internal implementation.

The routes not exposed in this BETA (those used by MaxGoodWeb, the messaging integrations and other parts of the platform) are NOT part of this contract and may change at any time — only /v1beta/* is covered.

6. Deprecation policy

If we must change a /v1beta/* endpoint in a way that is not backwards-compatible (rename a path, change a method, remove a field, change a type, narrow a behaviour), we will:

Publish a deprecation notice on the documentation page and on our Discord server, identifying the endpoint, the change, the planned cut-over date, and the migration steps.
Provide at least 1 week between the notice and the cut-over date during BETA (we expect this minimum to lengthen at GA).
Where reasonable, ship the replacement endpoint alongside the deprecated one so integrators can migrate ahead of the cut-over.

We will not silently change a published endpoint. Any internal change that affects published behaviour is a change-with-great-care event for the MaxGood.work engineering team — see §10.

6.1 Author branding in `response.response`

POST /v1beta/avatar/respond returns a reply at response.response (see the AvatarReply schema in the OpenAPI spec). When the reply cites one or more Foundation Content Titles, the licensed Author’s per-title attribution preference is rendered into that text as Markdown — one line per cited Foundation chunk — alongside the assistant’s prose. Foundation Content Title chunk references are NOT included in partner_content_ids; only Expertise (customer-uploaded) chunk references are.

Integrators SHOULD NOT strip the Author attribution from response.response when surfacing the reply to end users. The attribution carries the licensed Author’s branding into every reply that cites their work and is part of the licensing arrangement that makes Foundation content available to your Avatar. Removing it, replacing the rendered Markdown with a different rendering, or post-processing it out of the visible reply may put your Avatar’s Foundation content licensing at risk.

The Avatar’s stored display_references setting governs how the Expertise references are returned, and only them — it does not control Author attribution. An Avatar that has never set it displays references. Each Expertise reference is the URL <web portal>/reference/<chunk id> of a cited Expertise chunk. When the Avatar displays references, partner_content_ids is an empty array and, when the reply cites at least one Expertise chunk, response.response ends with a [References]: <url>, <url> line listing those URLs. When it does not, response.response carries no [References] line and partner_content_ids lists those URLs. Every citation of a reply is recorded whatever the setting, so Foundation Author usage is counted the same either way. To suppress Author attribution platform-wide for an Avatar, disable every Foundation Content Title for that Avatar via the Avatar Admin UI.

7. Rate limits, testing, fair use, and abuse

Phase 1 does not publish a hard rate limit. We reserve the right to:

Introduce per-key, per-endpoint, or per-Avatar rate limits in the future (with notice per §6 only if they are restrictive enough to break a documented use case).
Throttle or block individual keys that generate sustained pathological load, abusive content, or repeated unauthorized security-test traffic.

BETA does not enable a “test” mode or test API keys. ALL ACTIONS ON THE ENDPOINTS ARE PRODUCTION ACTIONS.

If you need a temporary Avatar set up for testing purposes, please request one from our team.

We ask integrators to keep usage proportionate to their Avatar’s normal activity. If you need to backfill or migrate large volumes through the API, please contact support first — see §12.

8. Data handling, privacy, and audit

The Public BETA API is subject to the same data-handling commitments as the rest of MaxGood.work:

We are working toward SOC 2 Type 2 compliance and we are GDPR compliant; data handling, access controls, and audit are scoped accordingly.
Every authentication attempt on a /v1beta/ endpoint, and every content mutation made through /v1beta/content/ or /v1beta/avatar/respond, is recorded in our internal audit log with the credential id, the Avatar, the endpoint, and the outcome.
Interactions created through /v1beta/avatar/respond are stored under the calling Avatar exactly as if they had been driven by an Avatar-admin action through the web UI or one of our messaging integrations.
We do not sell or share API-driven data with third parties.

Personal data sent to the API is subject to MaxGood.work’s published privacy policy and applicable GDPR commitments. Do not send personal data into the API that you do not have a lawful basis to process.

9. Liability — the BETA caveat

The BETA API is provided as-is during the BETA period, with no warranty beyond what is stated in your existing MaxGood.work service agreement / our general terms of service. While we use the same infrastructure as our production product and run automated security review on every change, BETA endpoints may exhibit behaviour that gets refined before GA. If your integration depends on a specific behaviour that is not explicitly documented as a stability promise in §5, please ask before depending on it.

10. “Change only with great care” — internal MaxGood.work rule

Every route file that backs a published /v1beta/* endpoint carries a BETA API PROGRAM marker comment. Internally, no engineering change may modify the request / response shape of a published endpoint without:

Confirming the change is backwards-compatible (per §5), or
Going through the deprecation process in §6.

This rule is enforced by code review, the pre-commit Codex review, and explicit reference in the project governance files (CLAUDE.md / AGENTS.md).

11. Versioning and the path to GA

The /v1beta/ prefix is a versioned layer of indirection on top of the existing internal handlers. Existing internal endpoints are NOT part of this contract and will continue to evolve independently. When the BETA exits, the public surface will be re-published under /v1/ with the GA stability promise; /v1beta/ will then be sunset on an announced schedule (typically six weeks or more) to give integrators time to migrate.

12. Support and feedback

Documentation: https://blog.maxgood.work/api-documentation-beta — OpenAPI specification, per-endpoint reference, deprecation notices, this contract.
Support, bug reports, feature requests, security: Join our Discord: https://discord.gg/xhkwCfYurk and check the v1beta-api-support channel.

We read every BETA report and welcome feedback on what is missing or awkward — it directly informs what the GA surface will look like.

Document history:

2026-05-20 — Phase 1 BETA, initial publication (Kanban Zone card #65, Story 5).
2026-06-02 — User management endpoints (GET/POST /users, GET/PUT/DELETE /users/{user_id}) added to the BETA surface (§3, §4) and the OpenAPI specification (Kanban Zone card #872, Phase 6).

Last published from
docs/v1beta-wordpress-page.html in the MaxGoodAI
repository. To request edits, open an issue or post in the
MaxGood.work Global User Community on Discord
v1beta-api-support channel.

MaxGood.work Public BETA API