Skip to content
engage-ai

API reference

Signup

Create your own organization. The only route needing no credential

For concepts and a walkthrough, read Quickstart.

Create your own organization

POST/organizations

Sign up. Creates the organization, a default agent profile, your login and a first API key in one transaction — all of them or none, because an organization without a profile receives messages it can never answer, and one without a key cannot be configured by any endpoint.

No credential is needed, and this is the only endpoint like that. It is limited by IP over two windows — SIGNUP_RATE_LIMIT_PER_MINUTE (5) for bursts and SIGNUP_RATE_LIMIT_PER_DAY (20) for the patient version of the same attack. A deployment that provisions tenants by hand turns it off with SELF_SERVICE_SIGNUP=false, and then this route does not exist at all.

The password and the key plaintext are shown once. Only hashes are stored, so neither can be recovered — losing one means replacing it, which is why the response is worth reading before it scrolls away.

Your password is generated rather than chosen, and mustChangePassword is set: replace it at POST /auth/password once you have signed in.

A signup with an email that already has an account returns 409, which does tell a caller that the address is registered. Sign-in deliberately reveals nothing of the kind; signup cannot match it without verifying the address out of band first, which this build does not do.

Auth
None
Body
application/json

Request body

  • namestringrequired

    Your business name, e.g. "Acme Outdoors".

    Max 255 characters

  • slugstring

    URL-safe identifier. Derived from the name when omitted. Immutable once set.

    Min 3 characters · Max 63 characters

  • defaultLocalestring

    Max 16 characters

  • defaultTimezonestring

    IANA name, e.g. Europe/London.

    Max 64 characters

  • personastring

    Seeds the default agent profile's persona. Editable afterwards.

    Max 4000 characters

  • ownerobjectrequired

    You. A password is generated and returned once, under login.

  • owner.emailstring (email)required

    You sign in with this.

    Max 320 characters

  • owner.namestring

    Max 255 characters

Response fields 201
  • organizationobjectrequired
  • organization.idstring (uuid)required
  • organization.slugstringrequired
  • organization.namestringrequired
  • organization.planstringrequired
  • agentProfileIdstring (uuid)required

    The default profile, created with conservative guardrails.

  • loginobjectrequired

    Hand this to the organization.

  • login.urlstringrequired

    Where to POST them.

  • login.emailstring (email)required
  • login.passwordstringrequired

    Shown once. It appears here and nowhere else — not in the audit log, not in any log line — and only a scrypt hash is stored. Lost means reissue, never retrieve.

  • login.mustChangePasswordtruerequired

    They are expected to replace it via POST /auth/password.

  • login.userIdstring (uuid)required
  • apiKeyobjectrequired
  • apiKey.idstring (uuid)required
  • apiKey.prefixstringrequired

    Non-secret. Safe to store and to quote in support.

  • apiKey.plaintextstringrequired

    Shown exactly once. Only a peppered hash is stored, so this cannot be recovered — issue a new key instead.

OrganizationProvisioned

  • organizationobjectrequired
  • organization.idstring (uuid)required
  • organization.slugstringrequired
  • organization.namestringrequired
  • organization.planstringrequired
  • agentProfileIdstring (uuid)required

    The default profile, created with conservative guardrails.

  • loginobjectrequired

    Hand this to the organization.

  • login.urlstringrequired

    Where to POST them.

  • login.emailstring (email)required
  • login.passwordstringrequired

    Shown once. It appears here and nowhere else — not in the audit log, not in any log line — and only a scrypt hash is stored. Lost means reissue, never retrieve.

  • login.mustChangePasswordtruerequired

    They are expected to replace it via POST /auth/password.

  • login.userIdstring (uuid)required
  • apiKeyobjectrequired
  • apiKey.idstring (uuid)required
  • apiKey.prefixstringrequired

    Non-secret. Safe to store and to quote in support.

  • apiKey.plaintextstringrequired

    Shown exactly once. Only a peppered hash is stored, so this cannot be recovered — issue a new key instead.

Responses

  • 201Created. Read the credentials now.
  • 401Missing, malformed, revoked or expired API key.
  • 404Not found, or not visible to this organization.
  • 422Request failed validation.
  • 429Rate limited.
  • 500Unexpected error. The correlationId ties it to our logs.
Request
curl -X POST "https://api.getengageai.app/organizations" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Copper Kettle Cafe",
    "owner": {
      "email": "manager@copperkettle.example",
      "name": "Sam Patel"
    }
  }'
Response · 201
{
  "organization": {
    "id": "3f6c2a1e-8b4d-4e7a-9c15-2d0b7e6f4a91",
    "slug": "copper-kettle-cafe",
    "name": "Trailhead Mid GTX Boot",
    "plan": "string"
  },
  "agentProfileId": "3f6c2a1e-8b4d-4e7a-9c15-2d0b7e6f4a91",
  "login": {
    "url": "https://acme.example/products/trailhead-mid",
    "email": "owner@acme.example",
    "password": "mFGVaAer-jKcyPp34-qxmLNojm",
    "mustChangePassword": true,
    "userId": "3f6c2a1e-8b4d-4e7a-9c15-2d0b7e6f4a91"
  },
  "apiKey": {
    "id": "3f6c2a1e-8b4d-4e7a-9c15-2d0b7e6f4a91",
    "prefix": "eng_live_312cf6e6",
    "plaintext": "eng_live_312cf6e6.fPCz8Qk…"
  }
}