Fillo Agents API

openapi: 3.2.0
info:
  title: Fillo So Agents API
  version: 1.0.0
  contact:
    name: Fillo support
    email: hello@fillo.so
    url: https://fillo.so/developers
  description: 'Operations tagged Agents 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: Agents
paths:
  /api/v1/manage/agents:
    get:
      tags:
      - Agents
      summary: List connected MCP clients
      operationId: listAgentGrants
      description: 'The MCP clients currently authorized against the key''s project, with the same ids Settings → Agents shows and each grant''s approval policy. Never returns key material. Tier A. Scope: workspace:manage.'
      responses:
        '200':
          description: The project's MCP grants.
          content:
            application/json:
              schema:
                type: object
                required:
                - grants
                properties:
                  grants:
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentGrant'
        '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/agents/{id}:
    delete:
      tags:
      - Agents
      summary: Disconnect an MCP client
      operationId: revokeAgentGrant
      description: 'Disconnect one MCP client. Its bearer stops working immediately and the human has to authorize it again from their agent, so this is destructive (Tier C): `confirm` must equal the grant id. An id outside the key''s project 404s. Scope: workspace:manage.'
      parameters:
      - name: id
        in: path
        required: true
        description: A grant id from the MCP client listing.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmTarget'
      responses:
        '200':
          description: The client was disconnected.
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - revoked
                - alreadyRevoked
                properties:
                  id:
                    type: string
                  revoked:
                    type: boolean
                    enum:
                    - true
                  alreadyRevoked:
                    type: boolean
        '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:
  schemas:
    AgentGrant:
      type: object
      required:
      - id
      - client
      - scopes
      - approvalPolicy
      - createdAt
      - lastUsedAt
      - expiresAt
      - expired
      properties:
        id:
          type: string
          description: The grant id — also the value a revocation must confirm with.
        client:
          type: string
        scopes:
          type: array
          items:
            type: string
        approvalPolicy:
          type: string
          enum:
          - ask
          - auto
          description: '`ask` sends every outward action to a human approval link first; `auto` runs Tier B directly. Destructive actions always need the link.'
        createdAt:
          type: string
          format: date-time
        lastUsedAt:
          type:
          - string
          - 'null'
          format: date-time
        expiresAt:
          type:
          - string
          - 'null'
          format: date-time
        expired:
          type: boolean
    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
  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'
  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)