Elaichi Teams API

openapi: 3.2.0
info:
  title: Elaichi Teams API
  version: 0.1.0
  description: 'Control-plane HTTP API for Elaichi, the MCP control plane for SaaS teams. Authenticate with an organization API token (create one in the Elaichi app under Settings → API tokens) sent as a bearer token, plus the `X-Organization-Id` header on org-scoped routes; the MCP and OAuth endpoints use their own protocols. A few actions are deliberately not available to an API token and must be done by a person in the Elaichi app: managing API and SCIM tokens, creating an organization, approving an access request, deleting an organization, and changing the two-factor requirement. The operations concerned say so. Endpoints used only by the Elaichi app itself (sign-in, consent screens, browser redirects, inbound webhooks) are not documented.'
servers:
- url: https://api.elaichi.ai
  description: Production
tags:
- name: Teams
paths:
  /team:
    get:
      operationId: listTeams
      summary: List teams
      tags:
      - Teams
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - result
                - next_cursor
                - prev_cursor
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
                  next_cursor:
                    type:
                    - string
                    - 'null'
                  prev_cursor:
                    type:
                    - string
                    - 'null'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: Lists the organization's teams, each with a member count and a few administrator names. Any member may read them. Cursor-paginated; `q` matches the team name.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/CursorQuery'
      - name: q
        in: query
        required: false
        description: Case-insensitive substring match on the team name. LIKE wildcards are matched literally. Max 200 characters.
        schema:
          type: string
          maxLength: 200
    post:
      operationId: createTeam
      summary: Create team
      tags:
      - Teams
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: 'Creates a team. Requires `team:create` (every Member holds it) or `team:manage`. Team names are unique within the organization. The caller becomes this team''s administrator immediately — the same auto-ownership every other created resource gets — whether or not their own id also appears in `member_ids`. `member_ids` optionally adds other existing organization members (`GET /member`) as ordinary members in the same call; an id that is not already an org member fails the whole call before anything is created. To promote one of them to administrator too, follow up with `PATCH /team/{id}/members/{userId}`. There is no way to create a team you do not administer: to stand one up for somebody else, create it and appoint them; a team administrator cannot remove another administrator, themselves included, so taking yourself off afterwards needs a `team:manage` holder.'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 120
                description:
                  type:
                  - string
                  - 'null'
                  maxLength: 2000
                member_ids:
                  type: array
                  maxItems: 50
                  items:
                    type: string
                    minLength: 1
                  description: User ids (`usr_…`) of existing organization members to add alongside the caller. Optional.
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
  /team/{id}:
    get:
      operationId: getTeam
      summary: Get team
      tags:
      - Teams
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: Returns one team with its member and administrator counts. Any member may read it; `404` when the team does not exist. The roster itself is `GET /team/{id}/member`.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Team id (`team_…`).
    patch:
      operationId: patchTeam
      summary: Update team
      tags:
      - Teams
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: Renames a team or changes its description. Merge-patch on `name`/`description`; membership is managed through the `/members` subroutes, never here. Allowed for holders of `team:manage` and for administrators of this particular team.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 120
                description:
                  type:
                  - string
                  - 'null'
                  maxLength: 2000
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Team id (`team_…`).
    delete:
      operationId: deleteTeam
      summary: Delete team
      tags:
      - Teams
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: Deletes a team. Irreversible. Removes the team and all of its memberships; members keep their org roles but lose anything granted through this team, including access to team-scoped connections and shares. Allowed for `team:manage` or an administrator of this team. A browser session must also pass a fresh step-up reauthentication in the app (without it the call answers `428 step_up_required`). An organization API token is not challenged.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Team id (`team_…`).
  /team/{id}/member:
    get:
      operationId: listTeamMembers
      summary: List team members
      tags:
      - Teams
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - result
                - next_cursor
                - prev_cursor
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/TeamMember'
                  next_cursor:
                    type:
                    - string
                    - 'null'
                  prev_cursor:
                    type:
                    - string
                    - 'null'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: Lists the members of a team. The team's roster, cursor-paginated — where a team row's `member_count` leads. A team row carries only a bounded `member_preview`, never the roster itself, so this is how a client reads who is in a team of any size. 404 when the team does not exist, which keeps an empty team distinguishable from a missing one.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Team id (`team_…`).
      - $ref: '#/components/parameters/LimitQuery'
      - $ref: '#/components/parameters/CursorQuery'
      - name: q
        in: query
        required: false
        description: Case-insensitive substring match on the member's name or email, applied server-side. LIKE wildcards are matched literally. Max 200 characters.
        schema:
          type: string
          maxLength: 200
  /team/{id}/members:
    post:
      operationId: addTeamMember
      summary: Add team member
      tags:
      - Teams
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: Adds one existing org member to the team and returns the whole team. Additive — it does not disturb the other members. Allowed for `team:manage` or an administrator of this team.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - user_id
              properties:
                user_id:
                  type: string
                  description: User id (`usr_…`) of an active org member.
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Team id (`team_…`).
  /team/{id}/members/{userId}:
    patch:
      operationId: setTeamMemberAdmin
      summary: Appoint or remove a team administrator
      tags:
      - Teams
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: 'Toggles team-admin rights for one member. Team administrators may rename their team, manage its ordinary members, appoint further administrators and delete it, and may manage team-scoped connections. Appointing (`is_admin: true`) is allowed for `team:manage` or an administrator of this team; standing an administrator down (`is_admin: false`) requires `team:manage`. Nobody may appoint themselves.'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - is_admin
              properties:
                is_admin:
                  type: boolean
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Team id (`team_…`).
      - name: userId
        in: path
        required: true
        schema:
          type: string
        description: User id (`usr_…`) of a team member.
    delete:
      operationId: removeTeamMember
      summary: Remove team member
      tags:
      - Teams
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: Removes one member from the team and returns the team. The member keeps their org membership and roles. A team administrator may remove ordinary members but not another administrator — that needs `team:manage`.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/OrganizationIdHeader'
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Team id (`team_…`).
      - name: userId
        in: path
        required: true
        schema:
          type: string
        description: User id (`usr_…`).
components:
  schemas:
    Team:
      type: object
      properties:
        id:
          type: string
          description: Team id (`team_…`).
        name:
          type: string
          description: Unique within the organization.
        description:
          type:
          - string
          - 'null'
        member_count:
          type: integer
          description: How many people are in the team. The row carries no roster array; `GET /team/{id}/member` is the roster.
        admin_count:
          type: integer
          description: How many of them administer the team.
        admin_preview:
          type: array
          description: The first few administrators, with display names already resolved, so a client can name them without a lookup per row. At most 5 — a preview for a hover, never the set; `admin_count` is the size. `name` and `email` are both null for someone who has left the organization.
          items:
            type: object
            properties:
              user_id:
                type: string
              name:
                type:
                - string
                - 'null'
              email:
                type:
                - string
                - 'null'
              avatar_url:
                type:
                - string
                - 'null'
                description: 'The person''s picture: their stored profile picture, else a Gravatar URL (`d=404`, 96px) derived from their email (the address itself is not sent), else null. Draw initials when it is null or the image fails to load.'
              is_admin:
                type: boolean
                description: Always true here.
        member_preview:
          type: array
          description: The same, for the first few members (administrators included, flagged by `is_admin`). `member_count` is the size; `GET /team/{id}/member` is the full, paginated roster.
          items:
            type: object
            properties:
              user_id:
                type: string
              name:
                type:
                - string
                - 'null'
              email:
                type:
                - string
                - 'null'
              avatar_url:
                type:
                - string
                - 'null'
                description: 'The person''s picture: their stored profile picture, else a Gravatar URL (`d=404`, 96px) derived from their email (the address itself is not sent), else null. Draw initials when it is null or the image fails to load.'
              is_admin:
                type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Success:
      type: object
      required:
      - success
      properties:
        success:
          type: boolean
    TeamMember:
      type: object
      properties:
        user_id:
          type: string
          description: Elaichi user id (`usr_…`).
        name:
          type:
          - string
          - 'null'
          description: Null (together with `email`) for someone who has left the organization.
        email:
          type:
          - string
          - 'null'
        avatar_url:
          type:
          - string
          - 'null'
          description: 'The person''s picture: their stored profile picture, else a Gravatar URL (`d=404`, 96px) derived from their email (the address itself is not sent), else null. Draw initials when it is null or the image fails to load.'
        is_admin:
          type: boolean
          description: 'Team administrator: may rename the team and manage its ordinary members.'
        joined_at:
          type: string
          format: date-time
          description: When they joined THIS team.
    Error:
      type: object
      required:
      - error
      description: The Elaichi error envelope. The MCP OAuth endpoints under `/oauth` are the exception — they return RFC 6749 errors instead (see `OAuthError`).
      properties:
        error:
          type: object
          required:
          - message
          - code
          properties:
            message:
              type: string
              description: Human-readable. 5xx messages are deliberately generic.
            code:
              type: string
              description: Stable machine-readable code, e.g. `not_found`, `subscription_required`.
            details:
              description: Structured detail for codes that carry one, e.g. `toolboxes_need_resolution`.
            feature:
              type: string
              description: The gated feature, on entitlement failures.
            plan:
              type:
              - string
              - 'null'
              enum:
              - personal
              - gold
              - black
              - null
          additionalProperties: true
  parameters:
    OrganizationIdHeader:
      name: X-Organization-Id
      in: header
      required: false
      description: Target organization (`org_…`). Required for cookie/session auth on org-scoped routes; optional for API tokens, which carry their organization, and rejected when it names a different one.
      schema:
        type: string
    CursorQuery:
      name: cursor
      in: query
      required: false
      description: Opaque cursor — pass the `next_cursor` from a previous response. Ignored by unpaginated endpoints.
      schema:
        type: string
    LimitQuery:
      name: limit
      in: query
      required: false
      description: Page size. Defaults to 50. Values above 200 are silently clamped to 200 rather than rejected; a value below 1, or a non-integer, is a 400. Ignored by the endpoints documented as unpaginated.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: session or API token
      description: '`Authorization: Bearer <token>` with an org-scoped API token (`elch_{org_id}_{64 hex}`), created in the Elaichi app under Settings → API tokens. The Elaichi app itself signs in with a session cookie, which is also accepted but is not meant for integrations. Two other credential families exist and are NOT interchangeable with this one: an MCP OAuth access token (`POST /mcp` only) and a SCIM token (`/scim/v2/*` only).'
    mcpOAuth:
      type: oauth2
      description: MCP OAuth access token, used only by `POST /mcp` — not interchangeable with `bearerAuth`. Discovered per RFC 9728/8414 at `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`.
      flows:
        authorizationCode:
          authorizationUrl: https://api.elaichi.ai/oauth/authorize
          tokenUrl: https://api.elaichi.ai/oauth/token
          scopes:
            mcp:read: Anything you can already see in Elaichi. Never secret values. It can also ask an admin for access to something restricted for you.
            mcp:write: Create and change teams, roles, toolboxes, templates and connections, and share access.
            mcp:destructive: Permanently delete data and remove access in Elaichi. This cannot be undone.
            mcp:tools: Run tools from the toolboxes you choose next, deleting in your connected apps included. It can also ask an admin for access to something restricted for you.
            openid: That you are signed in, and the user ID we use for you. Nothing else.
            email: Your email address, and whether it is verified. Apps use this to check your domain.