Airtable Shares API

openapi: 3.1.0
info:
  title: Airtable Audit Logs Shares API
  description: The Airtable API can be used to integrate your data in Airtable with any external system. The API closely follows REST semantics, uses JSON to encode objects, and relies on standard HTTP codes to signal operation outcomes. It provides full CRUD operations on records, comment management, and webhook subscriptions for real-time notifications.
  version: 1.0.0
  contact:
    name: Airtable
    url: https://airtable.com/developers
    email: support@airtable.com
  license:
    name: Proprietary
    url: https://airtable.com/tos
  termsOfService: https://airtable.com/tos
servers:
- url: https://api.airtable.com/v0
  description: Airtable API v0 production server
security:
- bearerAuth: []
tags:
- name: Shares
  description: Manage share links for bases within the enterprise
paths:
  /meta/bases/{baseId}/shares:
    get:
      operationId: listShares
      summary: Airtable List Share Links for a Base
      description: Returns a list of all active share links for the specified base. Each share includes its type, state, and the user who created it. This endpoint is available to enterprise administrators.
      tags:
      - Shares
      parameters:
      - $ref: '#/components/parameters/baseId'
      responses:
        '200':
          description: A list of share links for the base.
          content:
            application/json:
              schema:
                type: object
                properties:
                  shares:
                    type: array
                    items:
                      $ref: '#/components/schemas/Share'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /meta/bases/{baseId}/shares/{shareId}:
    patch:
      operationId: manageShare
      summary: Airtable Manage a Share Link
      description: Updates the configuration of an existing share link for a base. Can be used to enable or disable the share link, or update its access settings.
      tags:
      - Shares
      parameters:
      - $ref: '#/components/parameters/baseId'
      - $ref: '#/components/parameters/shareId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                state:
                  type: string
                  description: The desired state of the share link.
                  enum:
                  - enabled
                  - disabled
                isPasswordEnabled:
                  type: boolean
                  description: Whether password protection is enabled for the share link.
                password:
                  type: string
                  description: The password to set for the share link. Only applicable when isPasswordEnabled is true.
      responses:
        '200':
          description: The updated share link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Share'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteShare
      summary: Airtable Delete a Share Link
      description: Permanently deletes a share link for a base. Anyone who previously had access through this share link will immediately lose access.
      tags:
      - Shares
      parameters:
      - $ref: '#/components/parameters/baseId'
      - $ref: '#/components/parameters/shareId'
      responses:
        '200':
          description: Confirmation that the share link was deleted.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The authenticated user does not have enterprise admin permission.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: The request body contains invalid data.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Share:
      type: object
      description: A share link that provides external access to a base or view.
      properties:
        shareId:
          type: string
          description: The unique identifier of the share link.
          example: shrABC123def456
        type:
          type: string
          description: The type of share link.
          enum:
          - view
          - base
          - form
        state:
          type: string
          description: The current state of the share link.
          enum:
          - enabled
          - disabled
        createdByUserId:
          type: string
          description: The ID of the user who created the share link.
        createdTime:
          type: string
          format: date-time
          description: The time when the share link was created.
        baseId:
          type: string
          description: The ID of the base this share link provides access to.
        viewId:
          type: string
          description: The ID of the view this share link provides access to (for view-type shares).
        isPasswordEnabled:
          type: boolean
          description: Whether the share link is password-protected.
        effectivePermissionLevel:
          type: string
          description: The effective permission level granted by this share.
          enum:
          - read
          - comment
          - edit
      required:
      - shareId
      - type
      - state
    Error:
      type: object
      description: An error response from the Airtable API.
      properties:
        error:
          type: object
          properties:
            type:
              type: string
            message:
              type: string
          required:
          - type
          - message
  parameters:
    shareId:
      name: shareId
      in: path
      required: true
      description: The unique identifier of the share link (starts with 'shr').
      schema:
        type: string
        pattern: ^shr[a-zA-Z0-9]+$
    baseId:
      name: baseId
      in: path
      required: true
      description: The unique identifier of the base (starts with 'app').
      schema:
        type: string
        pattern: ^app[a-zA-Z0-9]+$
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Airtable uses Bearer token authentication. Provide a personal access token or OAuth access token in the Authorization header.
externalDocs:
  description: Airtable Web API Documentation
  url: https://airtable.com/developers/web/api/introduction