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

# Partner console

> Manage a tree of child organizations as an agency or reseller.

The partner console lets an agency or reseller manage a tree of descendant organizations from a single parent org. An organization holds a `parent_id`, so orgs form a hierarchy, and a parent can administer everything beneath it without being a member of each child.

Access is gated by the `child_organizations:manage` scope. Holders of that scope act on any org in their subtree purely through the parent-child relationship — they do not need to be a native member of a child to list it, view it, manage its members, or read its usage. Interactive login to a child org still requires native membership, which is why creating a child adds you to it as an admin.

```
parent org (you are a member here)
├── child A          ← you can manage, but are not a member
│   ├── grandchild A1
│   └── grandchild A2
└── child B
    └── grandchild B1
```

## Authorization model

Every partner-console route runs the same checks:

1. The caller is authenticated.
2. The caller holds the `child_organizations:manage` scope.
3. The target org is the caller's current org or a descendant of it.

The subtree check is backed by a recursive descendant lookup (`is_descendant_of`) rooted at the caller's organization. If the target is not in your subtree, the request is rejected.

<Note>
  Because user PATs (`pat_`) do not carry an organization, send the `X-Anyreach-Org: <organization_id>` header naming the org whose scope and subtree should apply. Org API keys (`ak_`) carry their org implicitly.
</Note>

## Capabilities

| Capability           | What it does                                                                                                                             |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| List direct children | Returns one level of children for a given parent. The console expands rows lazily, calling this per expanded node to load deeper levels. |
| Search descendants   | Recursive substring search over the whole subtree (by `slug` or `id`), returning each match with a breadcrumb `path`.                    |
| View a child         | Fetches a single child org's details.                                                                                                    |
| List child members   | Lists the members of a child org.                                                                                                        |
| Update member roles  | Sets a child member's organization roles.                                                                                                |
| Remove a member      | Removes a member from a child org.                                                                                                       |
| List invitations     | Lists a child org's pending invitations.                                                                                                 |
| Create an invitation | Invites a user to a child org by email.                                                                                                  |
| Usage view           | Aggregated usage across the whole subtree, or a single child's own usage.                                                                |

## Endpoints

All partner-console routes live under the `/admin/partner-console` prefix.

| Method   | Path                                                                      | Description                                                                                               |
| -------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `GET`    | `/admin/partner-console/organizations`                                    | List direct children. Optional `parent_id` query (defaults to your current org); must be in your subtree. |
| `GET`    | `/admin/partner-console/organizations/search`                             | Recursive descendant search. Query params: `q` (substring), `limit` (1–100, default 25).                  |
| `GET`    | `/admin/partner-console/organizations/{child_id}`                         | View one child org.                                                                                       |
| `GET`    | `/admin/partner-console/organizations/{child_id}/members`                 | List a child's members.                                                                                   |
| `PUT`    | `/admin/partner-console/organizations/{child_id}/members/{user_id}/roles` | Update a member's roles.                                                                                  |
| `DELETE` | `/admin/partner-console/organizations/{child_id}/members/{user_id}`       | Remove a member.                                                                                          |
| `GET`    | `/admin/partner-console/organizations/{child_id}/invitations`             | List a child's invitations.                                                                               |
| `POST`   | `/admin/partner-console/organizations/{child_id}/invitations`             | Invite a user to a child org.                                                                             |
| `GET`    | `/admin/partner-console/usage-summary`                                    | Usage summary for the subtree or a single child.                                                          |

### List direct children

`parent_id` defaults to your current org. The search root for descendant search is always your own org, read from your token, so you cannot probe a subtree you do not own.

```bash theme={null}
curl "https://api.anyreach.ai/admin/partner-console/organizations" \
  -H "Authorization: Bearer ak_..."
```

Each row contains `id`, `slug`, `domain`, `domain_setup_status`, and `parent_id`.

### Search descendants

```bash theme={null}
curl "https://api.anyreach.ai/admin/partner-console/organizations/search?q=acme&limit=25" \
  -H "Authorization: Bearer ak_..."
```

Each match returns `id`, `slug`, `domain`, `parent_id`, `depth`, and `path` — where `path` is a breadcrumb of slugs joined with `›` from the root to that node, so a picker can show where a deep match sits in the tree.

### Manage child members and invitations

These mirror the in-org member and invitation routes, but target a child by `child_id` and authorize through the subtree check instead of native membership. See [/organizations/members-and-invitations](/organizations/members-and-invitations) for the member and invitation model.

When you update a member's roles, only roles that are valid organization roles are applied; unrecognized role IDs are dropped.

## Usage view

The usage summary serves the **Usage** tab and supports two scopes.

| Scope           | Returns                                                                                                                  |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `all` (default) | Your current org plus every descendant, aggregated. No `org_id` needed.                                                  |
| `single`        | Only the selected child's own usage, excluding its nested descendants. Requires `org_id`, which must be in your subtree. |

```bash theme={null}
curl "https://api.anyreach.ai/admin/partner-console/usage-summary?from={iso8601}&to={iso8601}&scope=all" \
  -H "Authorization: Bearer ak_..."
```

| Query param | Required            | Description                                         |
| ----------- | ------------------- | --------------------------------------------------- |
| `from`      | Yes                 | Start of the window (ISO 8601).                     |
| `to`        | Yes                 | End of the window (ISO 8601). Must be after `from`. |
| `scope`     | No                  | `all` (default) or `single`.                        |
| `org_id`    | When `scope=single` | Target child org; must be in your subtree.          |

<Warning>
  The window must satisfy `to` after `from`, and the range cannot exceed 1 year (366 days). Out-of-range requests are rejected.
</Warning>

For the underlying metrics and how usage is metered, see [/organizations/usage-and-metering](/organizations/usage-and-metering).

## Create a child organization

Children are created through the standard org-create route with a `parent_id`, not a separate partner-console endpoint. When `parent_id` is set, the create flow verifies you hold `child_organizations:manage` and that `parent_id` is in your subtree before creating the org. You are added to the new org as an admin so you can sign in to it.

```bash theme={null}
curl -X POST "https://api.anyreach.ai/admin/organizations" \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme West",
    "slug": "acme-west",
    "parent_id": "<parent_org_id>"
  }'
```

Omit `parent_id` to create a standalone top-level org instead.

<Steps>
  <Step title="Open the Partner Console">
    The page is visible to users with the `child_organizations:manage` scope. It loads your direct children as a tree.
  </Step>

  <Step title="Pick a parent">
    Browse the tree or search descendants. Use the **+** affordance on any node — or **New organization** — to choose where the child is created.
  </Step>

  <Step title="Name the child">
    Enter a **Name** and **Slug**. The slug must be available. The dialog notes you will be added as the child's admin.
  </Step>

  <Step title="Manage it">
    The new child is selected automatically. Use the **Members** tab to invite or remove members and the **Usage** tab to view usage.
  </Step>
</Steps>

## Related

<CardGroup cols={2}>
  <Card title="Members and invitations" icon="users" href="/organizations/members-and-invitations">
    How members, roles, and email invitations work within an org.
  </Card>

  <Card title="Usage and metering" icon="gauge" href="/organizations/usage-and-metering">
    What is metered and how usage summaries are computed.
  </Card>
</CardGroup>