Agents

The agent API does everything a person can do in the dashboard: apply for access, create an account, sign in, and then manage organizations, audiences, flags and tests and read their results. The endpoints live under /api/agent/*, take JSON and return JSON. Errors are problem details with a stable code and a hint.

Every endpoint is in the OpenAPI spec, which is the full reference. These pages walk through them:

Getting startedCopy Anchor Link

1. Sign in, or create an account, for a bearer token.
2. List your organizations to get an organizationId. Without one, apply for access: the register code that is emailed on approval creates an organization.
3. Work in an environment of it: develop, staging or production.

Apply for accessCopy Anchor Link

Joins the waitlist, the same as the form on the homepage. The applicant gets a confirmation email, and a register code by email once the application is approved.

curl -X POST https://improve.obelism.studio/api/agent/apply \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","name":"Jane","company":"Acme"}'

{ "status": "pending" }

Create an accountCopy Anchor Link

curl -X POST https://improve.obelism.studio/api/agent/auth/sign-up \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","password":"a-long-Passw0rd!","firstName":"Jane","lastName":"Doe"}'

{
	"token": "Zm9vYmFyYmF6cXV4cXV1eGNvcmdlZ3JhdWx0",
	"tokenType": "Bearer",
	"expiresAt": "2026-11-07T12:00:00.000Z",
	"userId": "user_01H8XYZ",
	"verificationRequired": true
}

The password needs at least 8 characters, including a number and a special character. A six-digit code is emailed to the address.

Verify the emailCopy Anchor Link

Send the code from the email with the token from sign-up or sign-in:

curl -X POST https://improve.obelism.studio/api/agent/auth/verify-email \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"123456"}'

Codes are valid for 4 hours. Signing in with an unverified account emails a new one and returns verificationRequired: true.

Sign inCopy Anchor Link

curl -X POST https://improve.obelism.studio/api/agent/auth/sign-in \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","password":"a-long-Passw0rd!"}'

The response has the same shape as sign-up. The response is the same 401 invalid_credentials whether the email is unknown or the password is wrong.

Forgot your passwordCopy Anchor Link

Request a reset email:

curl -X POST https://improve.obelism.studio/api/agent/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com"}'

The answer is 202 whether or not the email has an account. The email links to /reset-password?token=…. That token is valid for 1 hour, and a newer request replaces it. Set the new password with it:

curl -X POST https://improve.obelism.studio/api/agent/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{"token":"…","newPassword":"an-even-longer-Passw0rd!"}'

This ends every session of the account and returns a new token, like sign-in.

Use the tokenCopy Anchor Link

Send the token on every request that needs an account:

curl https://improve.obelism.studio/api/agent/me \
  -H "Authorization: Bearer $TOKEN"

A token is valid for 30 days and is extended while it is in use. GET /api/agent/me returns the account and the current expiry, so it doubles as a check that a stored token still works. A 401 unauthorized means the token is missing, invalid or expired: sign in again.

The token is a full login session for the account. Store it like a password and never put it in client-side code.

Update your profileCopy Anchor Link

PATCH /api/agent/me changes the email address and name. Fields you leave out keep their value.

curl -X PATCH https://improve.obelism.studio/api/agent/me \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Jane","lastName":"Doe"}'

Change your passwordCopy Anchor Link

curl -X POST https://improve.obelism.studio/api/agent/me/password \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"currentPassword":"a-long-Passw0rd!","newPassword":"an-even-longer-Passw0rd!"}'

This ends every session of the account, including the token you sent. The response has a new token to continue with, in the same shape as sign-in.

Sign outCopy Anchor Link

curl -X POST https://improve.obelism.studio/api/agent/auth/sign-out \
  -H "Authorization: Bearer $TOKEN"

The token stops working straight away.

Rate limitsCopy Anchor Link

Over the limit the response is 429 rate_limited with a Retry-After header in seconds.