Organizations

Organization endpoints are dashboard endpoints for team workspaces. They use the signed-in app session, not X-NearIQ-Key. Owners and admins can manage members, invites, usage visibility, API key ownership, and activity logs according to their organization permissions.

Public v1 API keys can be scoped to an organization, but organization management itself is controlled through the signed-in dashboard session.

GET /api/orgs

Returns organizations owned by the signed-in user, organizations where the user is a member, and compatibility fields used by Settings.

curl "https://app.neariq.io/api/orgs" \
  -H "Cookie: <dashboard session cookie>"

{
  "ownedOrgs": [
    {
      "id": "88f2fd82-d093-4c2f-8427-4db6ea9a8ef1",
      "name": "Aster Grove Group",
      "plan": "agency",
      "subscription_status": "active",
      "max_seats": 5,
      "myRole": "owner",
      "members": [],
      "inviteHistory": []
    }
  ],
  "memberOrgs": [],
  "org": {
    "id": "88f2fd82-d093-4c2f-8427-4db6ea9a8ef1",
    "name": "Aster Grove Group"
  },
  "members": [],
  "inviteHistory": []
}

POST /api/orgs

Creates an organization and starts organization billing checkout for supported team plans.

curl -X POST "https://app.neariq.io/api/orgs" \
  -H "Content-Type: application/json" \
  -H "Cookie: <dashboard session cookie>" \
  -d '{ "name": "Aster Grove Group", "plan": "agency" }'

string

required

Organization name.

string

required

Team plan. Supported values are enforced by the API.

{
  "org": {
    "id": "88f2fd82-d093-4c2f-8427-4db6ea9a8ef1",
    "name": "Aster Grove Group",
    "plan": "agency",
    "subscription_status": "pending"
  },
  "checkoutUrl": "https://checkout.example.com/session"
}

PATCH /api/orgs/:id

Renames an organization or changes its plan. Only the organization owner can update it.

curl -X PATCH "https://app.neariq.io/api/orgs/88f2fd82-d093-4c2f-8427-4db6ea9a8ef1" \
  -H "Content-Type: application/json" \
  -H "Cookie: <dashboard session cookie>" \
  -d '{ "name": "Aster Grove Operators" }'

{
  "ok": true
}

For plan changes, send { "plan": "enterprise" }. The API blocks changes that would exceed seat limits.

DELETE /api/orgs/:id

Soft-deletes an organization and immediately revokes memberships, pending invites, and organization-scoped API keys. Only the owner can delete the organization.

curl -X DELETE "https://app.neariq.io/api/orgs/88f2fd82-d093-4c2f-8427-4db6ea9a8ef1" \
  -H "Content-Type: application/json" \
  -H "Cookie: <dashboard session cookie>" \
  -d '{ "confirm": "Aster Grove Operators" }'

{
  "ok": true,
  "deletedAt": "2026-05-30T18:00:00.000Z"
}

POST /api/orgs/invites

Creates or refreshes an invitation for a team member. Owners and admins with invite permission can send invites.

curl -X POST "https://app.neariq.io/api/orgs/invites" \
  -H "Content-Type: application/json" \
  -H "Cookie: <dashboard session cookie>" \
  -d '{
    "orgId": "88f2fd82-d093-4c2f-8427-4db6ea9a8ef1",
    "email": "manager@example.com",
    "role": "member"
  }'

{
  "ok": true,
  "invite": {
    "id": "0fd46a35-c3be-4d70-98ef-9f8e2a392111",
    "email": "manager@example.com",
    "role": "member",
    "expires_at": "2026-06-06T18:00:00.000Z"
  }
}

DELETE /api/orgs/invites/:id

Cancels a pending invitation in the signed-in user’s organization. Owners and admins can cancel invites.

curl -X DELETE "https://app.neariq.io/api/orgs/invites/0fd46a35-c3be-4d70-98ef-9f8e2a392111" \
  -H "Cookie: <dashboard session cookie>"

{
  "ok": true
}

GET /api/orgs/invites/me

Returns pending organization invitations for the signed-in user’s email address.

curl "https://app.neariq.io/api/orgs/invites/me" \
  -H "Cookie: <dashboard session cookie>"

{
  "invites": [
    {
      "id": "0fd46a35-c3be-4d70-98ef-9f8e2a392111",
      "token": "invite-token",
      "role": "member",
      "expires_at": "2026-06-06T18:00:00.000Z",
      "created_at": "2026-05-30T18:00:00.000Z",
      "orgName": "Aster Grove Group",
      "invitedBy": "owner@example.com"
    }
  ]
}

PATCH /api/orgs/members/:userId

Changes a member role or permission set. Owners and admins can update members, but the owner role cannot be changed.

curl -X PATCH "https://app.neariq.io/api/orgs/members/6f4d0d75-c4d9-45da-9e55-4a65f1d4f2f4" \
  -H "Content-Type: application/json" \
  -H "Cookie: <dashboard session cookie>" \
  -d '{
    "role": "admin",
    "permissions": {
      "manage_api_keys": true,
      "invite_members": true
    }
  }'

{
  "ok": true
}

DELETE /api/orgs/members/:userId

Removes a member from the organization or lets a member leave. Removing a member also revokes their organization-scoped API keys.

curl -X DELETE "https://app.neariq.io/api/orgs/members/6f4d0d75-c4d9-45da-9e55-4a65f1d4f2f4" \
  -H "Cookie: <dashboard session cookie>"

{
  "ok": true
}

GET /api/orgs/keys

Lists organization-scoped API keys visible to permitted team managers.

curl "https://app.neariq.io/api/orgs/keys" \
  -H "Cookie: <dashboard session cookie>"

{
  "keys": [
    {
      "id": "8d3f82e7-3f26-4f7f-b2fd-671807cb51b2",
      "name": "Reporting key",
      "scopes": ["analytics:read"],
      "created_at": "2026-05-30T18:00:00.000Z",
      "revoked_at": null
    }
  ],
  "canManageAll": true
}

DELETE /api/orgs/keys

Compatibility route for revoking an organization-scoped API key by request body.

curl -X DELETE "https://app.neariq.io/api/orgs/keys" \
  -H "Content-Type: application/json" \
  -H "Cookie: <dashboard session cookie>" \
  -d '{ "keyId": "8d3f82e7-3f26-4f7f-b2fd-671807cb51b2" }'

{
  "ok": true
}

DELETE /api/orgs/api-keys/:keyId

Revokes an organization-scoped member API key by path parameter.

curl -X DELETE "https://app.neariq.io/api/orgs/api-keys/8d3f82e7-3f26-4f7f-b2fd-671807cb51b2" \
  -H "Cookie: <dashboard session cookie>"

{
  "ok": true
}

GET /api/orgs/usage

Returns organization limits, total usage, and per-member usage for owners and admins.

curl "https://app.neariq.io/api/orgs/usage" \
  -H "Cookie: <dashboard session cookie>"

{
  "orgId": "88f2fd82-d093-4c2f-8427-4db6ea9a8ef1",
  "orgName": "Aster Grove Group",
  "orgPlan": "agency",
  "orgLimits": {
    "apiKeys": 10,
    "seats": 5,
    "competitors": 100,
    "locations": 10
  },
  "orgTotals": {
    "apiKeysUsed": 2,
    "apiKeysSuspended": 0,
    "seatsUsed": 3,
    "competitorsUsed": 28,
    "locationsUsed": 2
  },
  "members": []
}

GET /api/orgs/activity

Returns schema-backed team activity for owners and admins. Results are no-store and paginated.

curl "https://app.neariq.io/api/orgs/activity?limit=25&action=api_key" \
  -H "Cookie: <dashboard session cookie>"

number

Page size from 1 to 100. Defaults to 50.

number

Offset for pagination.

string

Optional user ID filter.

string

Optional action filter. Group aliases such as api_key, content, and competitor expand to related events.

{
  "activities": [
    {
      "id": "a9a0e93a-0c83-41ac-bf13-d3bbfbcf3e4f",
      "action": "api_key_created",
      "userId": "6f4d0d75-c4d9-45da-9e55-4a65f1d4f2f4",
      "userName": "Jordan Lee",
      "detail": "Created API key \"Reporting key\"",
      "createdAt": "2026-05-30T17:30:00.000Z"
    }
  ],
  "total": 1,
  "limit": 25,
  "offset": 0
}

Errors

Status	Meaning
`400`	Invalid body, unsupported plan, or seat-limit conflict
`401`	Missing dashboard session
`403`	User lacks owner/admin/permission access
`404`	Organization not found
`409`	Organization is already deleted
`500`	Billing or database operation failed

API Reference

Endpoints

Webhooks

GET /api/orgs

POST /api/orgs

PATCH /api/orgs/:id

DELETE /api/orgs/:id

POST /api/orgs/invites

DELETE /api/orgs/invites/:id

GET /api/orgs/invites/me

PATCH /api/orgs/members/:userId

DELETE /api/orgs/members/:userId

GET /api/orgs/keys

DELETE /api/orgs/keys

DELETE /api/orgs/api-keys/:keyId

GET /api/orgs/usage

GET /api/orgs/activity

Errors

​GET /api/orgs

​POST /api/orgs

​PATCH /api/orgs/:id

​DELETE /api/orgs/:id

​POST /api/orgs/invites

​DELETE /api/orgs/invites/:id

​GET /api/orgs/invites/me

​PATCH /api/orgs/members/:userId

​DELETE /api/orgs/members/:userId

​GET /api/orgs/keys

​DELETE /api/orgs/keys

​DELETE /api/orgs/api-keys/:keyId

​GET /api/orgs/usage

​GET /api/orgs/activity

​Errors

GET /api/orgs

POST /api/orgs

PATCH /api/orgs/:id

DELETE /api/orgs/:id

POST /api/orgs/invites

DELETE /api/orgs/invites/:id

GET /api/orgs/invites/me

PATCH /api/orgs/members/:userId

DELETE /api/orgs/members/:userId

GET /api/orgs/keys

DELETE /api/orgs/keys

DELETE /api/orgs/api-keys/:keyId

GET /api/orgs/usage

GET /api/orgs/activity

Errors