Fillo Members API

openapi: 3.2.0
info:
  title: Fillo So Members API
  version: 1.0.0
  contact:
    name: Fillo support
    email: hello@fillo.so
    url: https://fillo.so/developers
  description: 'Operations tagged Members across 2 of this provider''s published API definitions: fillo-so-openapi.json, fillo-so-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://fillo.so
security:
- bearerAuth: []
tags:
- name: Members
paths:
  /api/v1/manage/members:
    get:
      tags:
      - Members
      summary: List workspace members
      operationId: listWorkspaceMembers
      description: 'The workspace''s members and its pending, unexpired invitations, so an agent can resolve the id or email the member endpoints need. Never returns credentials. Tier A. Scope: members:manage.'
      responses:
        '200':
          description: Members and pending invitations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceMembers'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://fillo.so
  /api/v1/manage/members/invites:
    post:
      tags:
      - Members
      summary: Invite a member
      operationId: inviteWorkspaceMember
      description: 'Invite someone to the workspace by email, with an optional role (defaults to member). They receive an email and can join with that role, which makes this outward-facing (Tier B). An `fsk_` key has no session, so it acts as the human who minted it: their live role is the anti-escalation ceiling — a key can never invite above what its creator could grant today — and a key whose creator was removed or demoted is refused with 403. Scope: members:manage.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                role:
                  type: string
                  enum:
                  - owner
                  - admin
                  - member
                  description: Defaults to member.
      responses:
        '201':
          description: The created invitation.
          content:
            application/json:
              schema:
                type: object
                required:
                - invitation
                properties:
                  invitation:
                    type: object
                    required:
                    - id
                    - email
                    - role
                    - status
                    - expiresAt
                    properties:
                      id:
                        type: string
                      email:
                        type: string
                      role:
                        type: string
                        enum:
                        - owner
                        - admin
                        - member
                      status:
                        type: string
                        description: Better Auth's invitation status, e.g. "pending".
                      expiresAt:
                        type: string
                        format: date-time
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://fillo.so
  /api/v1/manage/members/invites/{id}:
    delete:
      tags:
      - Members
      summary: Cancel an invitation
      operationId: cancelWorkspaceInvitation
      description: 'Cancel a pending invitation. The invite link stops working immediately, and inviting the address again starts fresh, which keeps this routine (Tier A). The key acts as the human who minted it, exactly as the other member routes do, and the id is scoped to the key''s workspace first, so an invitation belonging to another workspace 404s indistinguishably from an unknown one. Scope: members:manage.'
      parameters:
      - name: id
        in: path
        required: true
        description: A pending invitation id from the members listing.
        schema:
          type: string
      responses:
        '200':
          description: The invitation was cancelled.
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - cancelled
                properties:
                  id:
                    type: string
                  cancelled:
                    type: boolean
                    enum:
                    - true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://fillo.so
  /api/v1/manage/members/{id}:
    patch:
      tags:
      - Members
      summary: Change a member's role
      operationId: setMemberRole
      description: 'Change a member''s workspace role. Their access changes immediately across every project, which makes this outward-facing (Tier B). An `fsk_` key has no session, so it acts as the human who minted it: their live role is the anti-escalation ceiling, a key whose creator was removed or demoted is refused with 403, and the workspace''s last owner can never be demoted. Scope: members:manage.'
      parameters:
      - name: id
        in: path
        required: true
        description: A member id or email address inside the key's workspace.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - role
              properties:
                role:
                  type: string
                  enum:
                  - owner
                  - admin
                  - member
      responses:
        '200':
          description: The member's new role.
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - email
                - role
                properties:
                  id:
                    type: string
                  email:
                    type: string
                  role:
                    type: string
                    enum:
                    - owner
                    - admin
                    - member
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
    delete:
      tags:
      - Members
      summary: Remove a member
      operationId: removeWorkspaceMember
      description: 'Remove someone from the workspace. They lose access to every project immediately and re-inviting them starts over, so this is destructive (Tier C): `confirm` must equal the member''s email address — the one human-readable id a manager can verify. The key acts as the human who minted it, and the workspace''s last owner can never be removed. Scope: members:manage.'
      parameters:
      - name: id
        in: path
        required: true
        description: A member id or email address inside the key's workspace.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmTarget'
      responses:
        '200':
          description: The member was removed.
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - email
                - removed
                properties:
                  id:
                    type: string
                  email:
                    type: string
                  removed:
                    type: boolean
                    enum:
                    - true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://fillo.so
components:
  responses:
    NotFound:
      description: No such resource in this project (returned instead of 403 for ids in other projects).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Per-key (120/min), per-workspace (240/min), or per-IP (300/min) rate limit exceeded. Retry after the Retry-After header.
      headers:
        RateLimit-Policy:
          description: Named quota policies and their limits/windows.
          schema:
            type: string
        RateLimit:
          description: Current remaining quota and seconds until reset for each named policy.
          schema:
            type: string
        RateLimit-Limit:
          description: 'Compatibility field: effective request limit.'
          schema:
            type: integer
        RateLimit-Remaining:
          description: 'Compatibility field: effective requests remaining.'
          schema:
            type: integer
        RateLimit-Reset:
          description: 'Compatibility field: seconds until the effective window resets.'
          schema:
            type: integer
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The key is valid but lacks the required scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PayloadTooLarge:
      description: The request body exceeded the 16 KiB management cap.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, malformed, unknown, revoked, or expired key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request (e.g. a body on a GET/DELETE, or a missing required query parameter).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: The request was understood but refused in this state — an unmet precondition, or a confirm value that did not match. Nothing was changed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    ConfirmTarget:
      type: object
      required:
      - confirm
      properties:
        confirm:
          type: string
          description: The exact target value this operation names in its description. A boolean true is rejected by the strict schema, so a bare confirmation can never stand in for a typed one.
      description: The typed confirmation a destructive (Tier C) operation requires. A mismatch is 409 and changes nothing.
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
    WorkspaceMembers:
      type: object
      required:
      - members
      - invitations
      properties:
        members:
          type: array
          items:
            type: object
            required:
            - id
            - userId
            - email
            - name
            - role
            - createdAt
            properties:
              id:
                type: string
                description: The member id the member endpoints address.
              userId:
                type: string
              email:
                type: string
              name:
                type: string
              role:
                type: string
              createdAt:
                type: string
                format: date-time
        invitations:
          type: array
          description: Pending, unexpired invitations only.
          items:
            type: object
            required:
            - id
            - email
            - role
            - expiresAt
            properties:
              id:
                type: string
              email:
                type: string
              role:
                type: string
              expiresAt:
                type: string
                format: date-time
      description: Never includes credentials.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'A project secret key (`fsk_…`). Scopes: forms:read, responses:read, respondents:read, responses:export, forms:write, forms:publish, storage:manage, webhooks:manage, settings:manage, integrations:manage, responses:manage, members:manage, workspace:manage, forms:delete, responses:delete, respondents:delete, workspace:delete. A request for a scope the key lacks returns 403 with a stable message naming the scope (e.g. `This key lacks the responses:export scope.`).'
externalDocs:
  description: Fillo developer resources
  url: https://fillo.so/developers
x-refined-from:
- fillo-so-openapi.json
- fillo-so-openapi.json
x-provenance:
  method: harvested
  publisher: Fillo
  source: https://fillo.so/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)