Organizations

Everything in Improve belongs to an organization, and tests, flags and audiences belong to one of its three environments: develop, staging and production. The dashboard remembers which one you are editing. The agent API names both in the path instead:

/api/agent/organizations/{organizationId}/{environment}/...

Organization-wide things, such as members and API tokens, leave out the environment:

/api/agent/organizations/{organizationId}/...

All of these need a bearer token.

List your organizationsCopy Anchor Link

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

{
	"organizations": [
		{
			"organizationId": "org_01H8XYZ",
			"name": "Acme",
			"slug": "acme",
			"subscription": "pro",
			"role": "editor"
		}
	]
}

GET /api/agent/organizations/{organizationId} returns one organization, plus the environments it has.

Create an organizationCopy Anchor Link

Creating an organization needs the register code that is emailed when an application for access is approved. Your account becomes its admin.

curl -X POST https://improve.obelism.studio/api/agent/organizations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme","registerCode":"…"}'

To delete one, an admin sends DELETE /api/agent/organizations/{organizationId}?confirm={slug}. The slug is the confirmation, like typing it in the dashboard. This deletes everything in it and cannot be undone.

API tokens and allowed originsCopy Anchor Link

These decide who may fetch the datafile and post analytics: servers send an API token, browsers must come from an allowed origin. They need the developer or admin role, including to read them, since the tokens are secrets.

GET .../security returns both per environment. PATCH .../security replaces the allowed origins of the environments you send:

curl -X PATCH https://improve.obelism.studio/api/agent/organizations/$ORG/security \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"production":{"allowedOrigins":["https://shop.example.com","https://www.example.com"]}}'

Each origin must be exact, such as https://shop.example.com, with no path or trailing slash, because browsers send it that way.

POST /api/agent/organizations/{organizationId}/{environment}/api-token generates a new token for the environment and returns it once. It replaces the current token, so servers still using the old one are refused from then on.

Members and invitesCopy Anchor Link

Managing members needs the admin role, like in the dashboard.

curl -X POST https://improve.obelism.studio/api/agent/organizations/$ORG/members \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"invites":[{"email":"sam@example.com","role":"editor"}]}'

Each person gets an email with a link to join, valid for 72 hours. Emails that are already a member or invited come back under skipped. A change that would leave the organization without an admin who has joined is refused.

To join an organization yourself, GET /api/agent/me/invites lists the organizations that invited your email, and POST /api/agent/me/invites/accept joins one, with either its organizationId or the token from the link in the invite email.

UsageCopy Anchor Link

GET /api/agent/organizations/{organizationId}/{environment}/usage returns this month's datafile and analytics requests against the plan. A limit of -1 is unlimited. Past the analytics limit, results freeze until the next month or an upgrade.

RolesCopy Anchor Link

Your role decides what you can do in an organization, the same as in the dashboard:

An action your role doesn't allow answers 403 insufficient_role. An organization you are not a member of answers 404 unknown_organization, the same as one that doesn't exist.