openapi: 3.0.3
info:
  title: AnyDB Ext Integration API
  version: 1.0.0
  description: |
    These endpoints are under API-key authentication using two required headers.
    Webhook events RECORD_CREATE and RECORD_UPDATE are debounced, so invocation can be delayed.
  
    **🔑 Please visit below link to learn more about how to get an API key:**
externalDocs:
  description: API key instructions
  url: https://www.anydb.com/support/integrations/typescript-sdk
servers:
  - url: https://app.anydb.com

tags:
  - name: Ext Integration

security:
  - AnyDbApiKey: []
    AnyDbEmail: []

paths:
  /api/integrations/ext/checkauth:
    post:
      tags: [Ext Integration]
      summary: Validate API key and email
      responses:
        "200":
          description: Authentication result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  email:
                    type: string
                  reason:
                    type: string

  /api/integrations/ext/register:
    post:
      tags: [Ext Integration]
      summary: Register a webhook
      description: Register a webhook and then use returned webhookId to subscribe for record events.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [teamid, url, name]
              properties:
                teamid:
                  type: string
                url:
                  type: string
                  format: uri
                name:
                  type: string
                description:
                  type: string
                timeout:
                  type: integer
                  minimum: 1000
                  maximum: 300000
                maxRetries:
                  type: integer
                  minimum: 0
                  maximum: 10
                backoffMs:
                  type: integer
                  minimum: 100
                  maximum: 60000
                customHeaders:
                  type: object
                  additionalProperties:
                    type: string
            example:
              teamid: TEAM_ID
              url: https://example.com/anydb-webhook
              name: My AnyDB Webhook
              description: Notify on record changes
      responses:
        "200":
          $ref: "#/components/responses/GenericResult"

  /api/integrations/ext/subscribe:
    post:
      tags: [Ext Integration]
      summary: Subscribe webhook to record event
      description: Subscribe a webhookId to RECORD_CREATE, RECORD_UPDATE, or RECORD_DELETE. RECORD_CREATE and RECORD_UPDATE are debounced and may be delayed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [webhookId, event]
              properties:
                webhookId:
                  type: string
                event:
                  type: string
                  enum:
                    [RECORD_CREATE, RECORD_UPDATE, RECORD_DELETE, RECORD_CRAETE]
            examples:
              recordCreate:
                summary: Subscribe for record create
                value:
                  webhookId: WEBHOOK_ID_FROM_REGISTER_RESPONSE
                  event: RECORD_CREATE
              recordUpdate:
                summary: Subscribe for record update
                value:
                  webhookId: WEBHOOK_ID_FROM_REGISTER_RESPONSE
                  event: RECORD_UPDATE
      responses:
        "200":
          $ref: "#/components/responses/GenericResult"

  /api/integrations/ext/unsubscribe:
    delete:
      tags: [Ext Integration]
      summary: Unsubscribe webhook from record event
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [webhookId, event]
              properties:
                webhookId:
                  type: string
                event:
                  type: string
                  enum:
                    [RECORD_CREATE, RECORD_UPDATE, RECORD_DELETE, RECORD_CRAETE]
      responses:
        "200":
          $ref: "#/components/responses/GenericResult"

  /api/integrations/ext/{webhookId}:
    put:
      tags: [Ext Integration]
      summary: Update webhook
      parameters:
        - name: webhookId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                url:
                  type: string
                  format: uri
                timeout:
                  type: integer
                  minimum: 1000
                  maximum: 300000
                customHeaders:
                  type: object
                  additionalProperties:
                    type: string
      responses:
        "200":
          $ref: "#/components/responses/GenericResult"
    delete:
      tags: [Ext Integration]
      summary: Delete webhook
      parameters:
        - name: webhookId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          $ref: "#/components/responses/GenericResult"

  /api/integrations/ext/listteams:
    get:
      tags: [Ext Integration]
      summary: List teams for authenticated user
      responses:
        "200":
          $ref: "#/components/responses/GenericResult"

  /api/integrations/ext/listdbsforteam:
    get:
      tags: [Ext Integration]
      summary: List databases for a team
      parameters:
        - $ref: "#/components/parameters/teamidQuery"
      responses:
        "200":
          $ref: "#/components/responses/GenericResult"

  /api/integrations/ext/record:
    get:
      tags: [Ext Integration]
      summary: Fetch a record by ID
      parameters:
        - $ref: "#/components/parameters/teamidQuery"
        - $ref: "#/components/parameters/adbidQuery"
        - $ref: "#/components/parameters/adoidQuery"
      responses:
        "200":
          $ref: "#/components/responses/GenericResult"

  /api/integrations/ext/list:
    get:
      tags: [Ext Integration]
      summary: List records with optional grouping, filters and pagination
      parameters:
        - $ref: "#/components/parameters/adbidQuery"
        - $ref: "#/components/parameters/teamidQuery"
        - name: groupby
          in: query
          schema:
            type: string
        - name: templateid
          in: query
          schema:
            type: string
        - name: templatename
          in: query
          schema:
            type: string
        - name: parentid
          in: query
          schema:
            type: string
        - name: pagesize
          in: query
          schema:
            type: integer
        - name: lastmarker
          in: query
          schema:
            type: string
        - name: sort
          in: query
          description: JSON string
          schema:
            type: string
        - name: filter
          in: query
          description: JSON string
          schema:
            type: string
        - name: previewcells
          in: query
          description: JSON string
          schema:
            type: string
      responses:
        "200":
          $ref: "#/components/responses/GenericResult"

  /api/integrations/ext/createrecord:
    post:
      tags: [Ext Integration]
      summary: Create a record
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [adbid, teamid, name]
              properties:
                adbid:
                  type: string
                teamid:
                  type: string
                name:
                  type: string
                attach:
                  type: string
                template:
                  type: string
                templatename:
                  type: string
                content:
                  type: array
                  items:
                    type: object
                    properties:
                      key:
                        type: string
      responses:
        "201":
          $ref: "#/components/responses/GenericResult"

  /api/integrations/ext/updaterecord:
    put:
      tags: [Ext Integration]
      summary: Update a record
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [meta]
              properties:
                meta:
                  type: object
                  required: [adoid, adbid, teamid, icon]
                  properties:
                    adoid:
                      type: string
                    adbid:
                      type: string
                    teamid:
                      type: string
                    icon:
                      type: string
                    name:
                      type: string
                    description:
                      type: string
                    followup:
                      type: number
                    locked:
                      type: boolean
                    attach:
                      type: string
                    status:
                      type: string
                    assignees:
                      type: object
                content:
                  type: array
                  items:
                    type: object
                    properties:
                      key:
                        type: string
      responses:
        "200":
          $ref: "#/components/responses/GenericResult"

  /api/integrations/ext/getuploadurl:
    get:
      tags: [Ext Integration]
      summary: Get direct upload URL
      parameters:
        - name: filename
          in: query
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/teamidQuery"
        - $ref: "#/components/parameters/adbidQuery"
        - $ref: "#/components/parameters/adoidQuery"
        - name: filesize
          in: query
          required: true
          schema:
            type: integer
        - name: cellpos
          in: query
          schema:
            type: string
        - name: import_content
          in: query
          schema:
            type: boolean
        - name: import_media
          in: query
          schema:
            type: boolean
      responses:
        "200":
          $ref: "#/components/responses/GenericResult"

  /api/integrations/ext/completeupload:
    put:
      tags: [Ext Integration]
      summary: Complete upload
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [filesize, teamid, adbid]
              properties:
                filesize:
                  type: integer
                teamid:
                  type: string
                adbid:
                  type: string
                adoid:
                  type: string
                cellpos:
                  type: string
                import_content:
                  type: boolean
                import_attachto:
                  type: string
                import_templateid:
                  type: string
                import_filename:
                  type: string
                import_image:
                  type: boolean
      responses:
        "200":
          $ref: "#/components/responses/GenericResult"

  /api/integrations/ext/search:
    get:
      tags: [Ext Integration]
      summary: Search records
      parameters:
        - $ref: "#/components/parameters/adbidQuery"
        - $ref: "#/components/parameters/teamidQuery"
        - name: search
          in: query
          required: true
          schema:
            type: string
        - name: parentid
          in: query
          schema:
            type: string
        - name: start
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        "201":
          $ref: "#/components/responses/GenericResult"

  /api/integrations/ext/download:
    get:
      tags: [Ext Integration]
      summary: Get download URL or redirect
      parameters:
        - $ref: "#/components/parameters/teamidQuery"
        - $ref: "#/components/parameters/adbidQuery"
        - $ref: "#/components/parameters/adoidQuery"
        - name: cellpos
          in: query
          required: true
          schema:
            type: string
        - name: redirect
          in: query
          schema:
            type: boolean
        - name: preview
          in: query
          schema:
            type: boolean
      responses:
        "200":
          $ref: "#/components/responses/GenericResult"
        "302":
          description: Redirect to file URL (when redirect=true)

  /api/integrations/ext/remove:
    delete:
      tags: [Ext Integration]
      summary: Remove record from one or more parents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [adoid, adbid, teamid, removefromids]
              properties:
                adoid:
                  type: string
                adbid:
                  type: string
                teamid:
                  type: string
                removefromids:
                  oneOf:
                    - type: string
                      description: Comma-separated list
                    - type: array
                      items:
                        type: string
      responses:
        "200":
          $ref: "#/components/responses/GenericResult"

  /api/integrations/ext/copyrecord:
    post:
      tags: [Ext Integration]
      summary: Duplicate record
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [adoid, adbid, teamid]
              properties:
                adoid:
                  type: string
                adbid:
                  type: string
                teamid:
                  type: string
                dstadbid:
                  type: string
                attachto:
                  type: string
                attachmentsmode:
                  type: string
                  enum: [noattachments, link, duplicate]
      responses:
        "200":
          $ref: "#/components/responses/GenericResult"

  /api/integrations/ext/share:
    put:
      tags: [Ext Integration]
      summary: Create share for record
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [teamid, adbid, adoid, role, withattachments]
              properties:
                teamid:
                  type: string
                adbid:
                  type: string
                adoid:
                  type: string
                role:
                  type: string
                  enum: [viewer, editor]
                withattachments:
                  type: string
                shared_userids:
                  type: string
                  description: CSV user IDs
                shared_emails:
                  type: string
                  description: CSV emails
                shared_groupids:
                  type: string
                  description: CSV group IDs
                name:
                  type: string
                share_expiry_enable:
                  type: boolean
                share_expiry_date:
                  type: string
      responses:
        "200":
          $ref: "#/components/responses/GenericResult"

  /api/integrations/ext/share/{shareid}:
    delete:
      tags: [Ext Integration]
      summary: Remove share
      parameters:
        - name: shareid
          in: path
          required: true
          schema:
            type: string
        - name: teamid
          in: query
          required: true
          schema:
            type: string
        - name: sharetype
          in: query
          required: true
          schema:
            type: string
            enum: [form, item]
      responses:
        "200":
          $ref: "#/components/responses/GenericResult"

components:
  securitySchemes:
    AnyDbApiKey:
      type: apiKey
      in: header
      name: x-anydb-api-key
    AnyDbEmail:
      type: apiKey
      in: header
      name: x-anydb-email

  parameters:
    teamidQuery:
      name: teamid
      in: query
      required: true
      schema:
        type: string
    adbidQuery:
      name: adbid
      in: query
      required: true
      schema:
        type: string
    adoidQuery:
      name: adoid
      in: query
      required: true
      schema:
        type: string

  responses:
    GenericResult:
      description: Standard Result wrapper response
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true