agentleFS API

openapi: 3.1.0
info:
  title: agentleFS API
  version: '2026-11-01'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-01: 21 operation(s) read from 3 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; agentleFS has published no machine-readable contract that the
    pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 3
    documentation: 18
    pages-with-code: 1
    pages-read: 3
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-01'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://agentlefs.com/docs/api
  - https://agentlefs.com/docs/faq
  - https://agentlefs.com/docs/connect
servers:
- url: https://mcp.agentlefs.com
paths:
  /mcp:
    post:
      operationId: post_mcp
      tags:
      - Mcp
      summary: Remote HTTP (Streamable HTTP) — afs_ header POST to /mcp — one endpoint, the whole toolset.
      description: Send a JSON payload containing the MCP server configuration. The request must include an Authorization bearer header with an
        afs_ token.
      x-source: https://agentlefs.com/docs/connect
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostMcpRequest'
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/documents:
    get:
      operationId: get_v1_documents
      tags:
      - Documents
      summary: list documents in a folder
      x-source: https://agentlefs.com/docs/api
      parameters:
      - name: location
        in: query
        required: false
        schema:
          type: string
        description: folder path to list documents from
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer API key
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_v1_documents
      tags:
      - Documents
      summary: create a document
      x-source: https://agentlefs.com/docs/api
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer API key
      - name: Content-Type
        in: header
        required: true
        schema:
          type: string
        description: application/json
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
        description: unique key to make the request idempotent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1DocumentsRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/documents/handbook/onboarding/day-one.md:
    get:
      operationId: get_v1_documents_handbook_onboarding_day_one_md
      tags:
      - Documents
      summary: GET /v1/documents/handbook/onboarding/day-one.md
      x-source: https://agentlefs.com/docs/api
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl -sD- -o /dev/null "https://agentlefs.com/v1/documents/handbook/onboarding/day-one.md"  -H "Authorization: Bearer afs_your_api_key"
          | grep -i ''^etag:'' | cut -d'' '' -f2 | tr -d ''\r'')'
    put:
      operationId: put_v1_documents_handbook_onboarding_day_one_md
      tags:
      - Documents
      summary: PUT /v1/documents/handbook/onboarding/day-one.md
      x-source: https://agentlefs.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutV1DocumentsHandbookOnboardingDayOneMdRequest'
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl -s -X PUT "https://agentlefs.com/v1/documents/handbook/onboarding/day-one.md"  -H "Authorization: Bearer afs_your_api_key"  -H
          "Content-Type: application/json"  -H "If-Match: $ETAG"  -d ''{"content": "# Day one\n\nUpdated."}'' Lists are paginated with an opaque
          next_cursor . Pass it back to get the next page, and stop when it comes back null . A cursor belongs to the query and the key that prod'
  /v1/documents/{location}:
    delete:
      operationId: delete_v1_documents_location
      tags:
      - Documents
      summary: delete a document
      x-source: https://agentlefs.com/docs/api
      parameters:
      - name: location
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer API key
      - name: If-Match
        in: header
        required: true
        schema:
          type: string
        description: ETag value from a prior read
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    get:
      operationId: get_v1_documents_location
      tags:
      - Documents
      summary: read a document
      x-source: https://agentlefs.com/docs/api
      parameters:
      - name: location
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer API key
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1DocumentsLocationResponse'
      x-evidence:
        kind: documentation
    put:
      operationId: put_v1_documents_location
      tags:
      - Documents
      summary: update a document
      x-source: https://agentlefs.com/docs/api
      parameters:
      - name: location
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer API key
      - name: Content-Type
        in: header
        required: true
        schema:
          type: string
        description: application/json
      - name: If-Match
        in: header
        required: true
        schema:
          type: string
        description: ETag value from a prior read
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutV1DocumentsLocationRequest'
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/folders:
    get:
      operationId: get_v1_folders
      tags:
      - Folders
      summary: list folders, one level
      x-source: https://agentlefs.com/docs/api
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer API key
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_v1_folders
      tags:
      - Folders
      summary: POST /v1/folders
      x-source: https://agentlefs.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1FoldersRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl -s "https://agentlefs.com/v1/folders"  -H "Authorization: Bearer afs_your_api_key" An empty list is a real answer, not
          a failure. The key reaches only what its principal has been granted, so grant it access in Permissions first. A 404 does not mean you
          got the path wrong If your key is not permitted to read something, the API returns 404 with exactly the response it would give for something
          t'
  /v1/folders/export:
    get:
      operationId: get_v1_folders_export
      tags:
      - Folders
      summary: download a folder as a zip
      x-source: https://agentlefs.com/docs/api
      parameters:
      - name: location
        in: query
        required: false
        schema:
          type: string
        description: folder path to export
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer API key
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/grants:
    delete:
      operationId: delete_v1_grants
      tags:
      - Grants
      summary: revoke a grant
      x-source: https://agentlefs.com/docs/api
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    get:
      operationId: get_v1_grants
      tags:
      - Grants
      summary: who can reach a scope
      x-source: https://agentlefs.com/docs/api
      parameters:
      - name: scope_type
        in: query
        required: false
        schema:
          type: string
        description: type of the scope
      - name: scope_id
        in: query
        required: false
        schema:
          type: string
        description: identifier of the scope
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_v1_grants
      tags:
      - Grants
      summary: grant a role on a scope
      x-source: https://agentlefs.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1GrantsRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/health:
    get:
      operationId: get_v1_health
      tags:
      - Health
      summary: liveness, and which build is serving
      x-source: https://agentlefs.com/docs/api
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/moves:
    post:
      operationId: post_v1_moves
      tags:
      - Moves
      summary: move to another folder
      x-source: https://agentlefs.com/docs/api
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer API key
      - name: Content-Type
        in: header
        required: true
        schema:
          type: string
        description: application/json
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
        description: unique key to make the request idempotent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1MovesRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/openapi.yaml:
    get:
      operationId: get_v1_openapi_yaml
      tags:
      - Openapi
      summary: this API's OpenAPI spec
      x-source: https://agentlefs.com/docs/api
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/renames:
    post:
      operationId: post_v1_renames
      tags:
      - Renames
      summary: rename in place
      x-source: https://agentlefs.com/docs/api
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer API key
      - name: Content-Type
        in: header
        required: true
        schema:
          type: string
        description: application/json
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
        description: unique key to make the request idempotent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1RenamesRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/search:
    get:
      operationId: get_v1_search
      tags:
      - Search
      summary: search reachable content
      x-source: https://agentlefs.com/docs/api
      parameters:
      - name: q
        in: query
        required: false
        schema:
          type: string
        description: search query
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/undeletes:
    post:
      operationId: post_v1_undeletes
      tags:
      - Undeletes
      summary: undo the last delete at a location
      x-source: https://agentlefs.com/docs/api
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer API key
      - name: Content-Type
        in: header
        required: true
        schema:
          type: string
        description: application/json
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
        description: unique key to make the request idempotent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1UndeletesRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/uploads:
    post:
      operationId: post_v1_uploads
      tags:
      - Uploads
      summary: upload files by sha256 and size; PUT each to its url
      x-source: https://agentlefs.com/docs/api
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Bearer API key
      - name: Content-Type
        in: header
        required: true
        schema:
          type: string
        description: application/json
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
        description: unique key to make the request idempotent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1UploadsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1UploadsResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    PostMcpRequest:
      type: object
      properties:
        mcpServers:
          type: object
          description: Map of MCP server configurations.
        mcpServers.agentlefs:
          type: object
          description: Configuration for the agentlefs MCP server.
        mcpServers.agentlefs.url:
          type: string
          description: URL of the MCP endpoint.
        mcpServers.agentlefs.headers:
          type: object
          description: Headers to include when calling the MCP server.
        mcpServers.agentlefs.headers.Authorization:
          type: string
          description: Bearer token for authentication (e.g., afs_your_token_here).
      required:
      - mcpServers
      - mcpServers.agentlefs
      - mcpServers.agentlefs.url
      - mcpServers.agentlefs.headers
      - mcpServers.agentlefs.headers.Authorization
    PostV1DocumentsRequest:
      type: object
      properties:
        location:
          type: string
          description: full path of the document to create
        content:
          type: string
          description: markdown content of the document
      required:
      - location
      - content
    PutV1DocumentsHandbookOnboardingDayOneMdRequest:
      type: object
      properties:
        content:
          type: string
    GetV1DocumentsLocationResponse:
      type: object
      properties:
        content:
          type: string
          description: document markdown
        ETag:
          type: string
          description: version identifier returned in response header
    PutV1DocumentsLocationRequest:
      type: object
      properties:
        content:
          type: string
          description: new markdown content
      required:
      - content
    PostV1FoldersRequest:
      type: object
      properties:
        location:
          type: string
        content:
          type: string
    PostV1GrantsRequest:
      type: object
      properties:
        Idempotency-Key:
          type: string
          description: Idempotency key for the request
      required:
      - Idempotency-Key
    PostV1MovesRequest:
      type: object
      properties:
        source:
          type: string
          description: current location
        destination:
          type: string
          description: target location
        acknowledge_access_change:
          type: boolean
          description: set true to confirm widening access
      required:
      - source
      - destination
    PostV1RenamesRequest:
      type: object
      properties:
        source:
          type: string
          description: current location
        destination:
          type: string
          description: new location
      required:
      - source
      - destination
    PostV1UndeletesRequest:
      type: object
      properties:
        location:
          type: string
          description: path where the delete was performed
      required:
      - location
    PostV1UploadsRequest:
      type: object
      properties:
        files:
          type: array
          description: list of objects with sha256 and size for each file
      required:
      - files
    PostV1UploadsResponse:
      type: object
      properties:
        upload_urls:
          type: object
          description: mapping of file identifiers to pre‑signed PUT URLs
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Documents
- name: Folders
- name: Grants
- name: Health
- name: Mcp
- name: Moves
- name: Openapi
- name: Renames
- name: Search
- name: Undeletes
- name: Uploads