> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neariq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizations

> Session-authenticated organization, member, invite, usage, and team activity endpoints.

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.

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

## GET /api/orgs

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

<RequestExample>
  ```bash cURL theme={null}
  curl "https://app.neariq.io/api/orgs" \
    -H "Cookie: <dashboard session cookie>"
  ```
</RequestExample>

```json theme={null}
{
  "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.

```bash theme={null}
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" }'
```

<ParamField body="name" type="string" required>
  Organization name.
</ParamField>

<ParamField body="plan" type="string" required>
  Team plan. Supported values are enforced by the API.
</ParamField>

```json theme={null}
{
  "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.

```bash theme={null}
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" }'
```

```json theme={null}
{
  "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.

```bash theme={null}
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" }'
```

```json theme={null}
{
  "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.

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "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.

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

```json theme={null}
{
  "ok": true
}
```

## GET /api/orgs/invites/me

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

```bash theme={null}
curl "https://app.neariq.io/api/orgs/invites/me" \
  -H "Cookie: <dashboard session cookie>"
```

```json theme={null}
{
  "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.

```bash theme={null}
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
    }
  }'
```

```json theme={null}
{
  "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.

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

```json theme={null}
{
  "ok": true
}
```

## GET /api/orgs/keys

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

```bash theme={null}
curl "https://app.neariq.io/api/orgs/keys" \
  -H "Cookie: <dashboard session cookie>"
```

```json theme={null}
{
  "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.

```bash theme={null}
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" }'
```

```json theme={null}
{
  "ok": true
}
```

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

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

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

```json theme={null}
{
  "ok": true
}
```

## GET /api/orgs/usage

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

```bash theme={null}
curl "https://app.neariq.io/api/orgs/usage" \
  -H "Cookie: <dashboard session cookie>"
```

```json theme={null}
{
  "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.

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

<ParamField query="limit" type="number">
  Page size from 1 to 100. Defaults to 50.
</ParamField>

<ParamField query="offset" type="number">
  Offset for pagination.
</ParamField>

<ParamField query="member" type="string">
  Optional user ID filter.
</ParamField>

<ParamField query="action" type="string">
  Optional action filter. Group aliases such as `api_key`, `content`, and `competitor` expand to related events.
</ParamField>

```json theme={null}
{
  "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                   |