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

1. Sign in to MaxGoodWeb as the Avatar Owner or an Avatar Admin
   of the Enterprise Avatar you want to integrate.
2. Open Avatar Admin > Account.
3. 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.
4. 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.
5. 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:

1. 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.
2. 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).
3. 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.

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:

1. 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.
2. 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).
3. 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.

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:

1. 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.
2. Provide at least 1 week between the notice and the cut-over date during BETA (we expect this minimum to lengthen at GA).
3. 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 Owner’s existing display_references toggle continues to govern the display of partner_content_ids (the Expertise references) only — it does not control Author attribution. 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/UMGkK4ES 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 (KanbanZone 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 (KanbanZone 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 Discord
v1beta-api-support channel.