openapi: 3.1.0
info:
  title: 1Password Connect Server Accounts Files API
  description: The 1Password Connect Server API provides secure access to 1Password items and vaults in your company's apps and cloud infrastructure through a private REST API. Connect Servers bridge the gap between 1Password and your infrastructure by enabling programmatic access to secrets stored in shared vaults. You can create, read, update, and delete items, manage vaults, and retrieve files attached to items.
  version: 1.8.1
  contact:
    name: 1Password Support
    url: https://support.1password.com/
  termsOfService: https://1password.com/legal/terms-of-service/
  license:
    name: MIT
    url: https://github.com/1Password/connect/blob/main/LICENSE
servers:
- url: http://localhost:8080
  description: Local Connect Server (default port 8080)
security:
- bearerAuth: []
tags:
- name: Files
  description: Operations for listing and retrieving files attached to items.
paths:
  /v1/vaults/{vaultUuid}/items/{itemUuid}/files:
    get:
      operationId: listFiles
      summary: 1Password List Files Attached to an Item
      description: Returns a list of all files attached to the specified item within the given vault. Each file entry includes its unique identifier, name, size, and content path.
      tags:
      - Files
      parameters:
      - $ref: '#/components/parameters/vaultUuidParam'
      - $ref: '#/components/parameters/itemUuidParam'
      - name: inline_files
        in: query
        description: When set to true, file content is included inline in the response.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Successfully retrieved files
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/File'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/vaults/{vaultUuid}/items/{itemUuid}/files/{fileUuid}:
    get:
      operationId: getFileById
      summary: 1Password Get File Details
      description: Returns the metadata for a specific file attached to an item within the specified vault.
      tags:
      - Files
      parameters:
      - $ref: '#/components/parameters/vaultUuidParam'
      - $ref: '#/components/parameters/itemUuidParam'
      - $ref: '#/components/parameters/fileUuidParam'
      - name: inline_files
        in: query
        description: When set to true, file content is included inline in the response.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Successfully retrieved file details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/vaults/{vaultUuid}/items/{itemUuid}/files/{fileUuid}/content:
    get:
      operationId: getFileContent
      summary: 1Password Get File Content
      description: Returns the raw content of a specific file attached to an item within the specified vault. The response is the binary file content.
      tags:
      - Files
      parameters:
      - $ref: '#/components/parameters/vaultUuidParam'
      - $ref: '#/components/parameters/itemUuidParam'
      - $ref: '#/components/parameters/fileUuidParam'
      responses:
        '200':
          description: Successfully retrieved file content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    itemUuidParam:
      name: itemUuid
      in: path
      description: The UUID of the item.
      required: true
      schema:
        type: string
        format: uuid
    fileUuidParam:
      name: fileUuid
      in: path
      description: The UUID of the file.
      required: true
      schema:
        type: string
        format: uuid
    vaultUuidParam:
      name: vaultUuid
      in: path
      description: The UUID of the vault.
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    Error:
      type: object
      description: Represents an error response from the Connect server.
      properties:
        status:
          type: integer
          description: The HTTP status code.
        message:
          type: string
          description: A human-readable error message.
    File:
      type: object
      description: Represents a file attached to an item in a vault.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier for the file.
        name:
          type: string
          description: The name of the file.
        size:
          type: integer
          description: The size of the file in bytes.
        content_path:
          type: string
          description: The API path to retrieve the file content.
        section:
          $ref: '#/components/schemas/SectionRef'
        content:
          type: string
          format: byte
          description: The base64-encoded file content, included when inline_files is true.
    SectionRef:
      type: object
      description: A reference to a section within an item.
      properties:
        id:
          type: string
          description: The unique identifier of the referenced section.
  responses:
    Unauthorized:
      description: Authentication credentials are missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: A Connect server access token generated from 1Password. Each request must include this token in the Authorization header.
externalDocs:
  description: 1Password Connect Server API Reference
  url: https://developer.1password.com/docs/connect/api-reference/