BAMF.ai Profile Packages API

openapi: 3.2.0
info:
  title: BAMF Developer Platform Profile Packages API
  version: 0.1.0
servers:
- url: https://api.bamf.ai/v1
security:
- BearerAuth: []
tags:
- name: Profile Packages
paths:
  /profile-packages/capture-status:
    get:
      summary: Get safe profile capture status
      description: Returns Original/current capture timestamps and verification status for one creator. Never returns capture provenance, browser runs, raw provider payloads, cookies, or secrets. Requires profile_packages:read.
      parameters:
      - name: creator_id
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Safe profile capture status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericDataResponse'
      tags:
      - Profile Packages
      operationId: getProfilePackagesCaptureStatus
      x-operation-id-source: derived
  /profile-packages/snapshots:
    post:
      summary: Ingest an immutable Profile Studio capture
      description: Stores a creator-authorized, bounded snapshot handed off by BAMFOS. Requires profile_packages:write and Idempotency-Key. The caller supplies the exact snapshot UUID. A retry with the same UUID and canonical content returns 200 idempotently; a differing payload returns 409. Original is accepted only for a verified pre-BAMF capture. This endpoint stores evidence only and never changes LinkedIn.
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 8
          maxLength: 200
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfileSnapshotIngestRequest'
      responses:
        '200':
          description: Existing identical snapshot returned idempotently
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileSnapshotIngestResponse'
        '201':
          description: Snapshot ingested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileSnapshotIngestResponse'
        '400':
          description: Invalid, unsafe, unbounded, or non-Original-eligible snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: UUID, content hash, creator, supersession, or Original-baseline conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Profile Packages
      operationId: postProfilePackagesSnapshots
      x-operation-id-source: derived
  /profile-packages:
    get:
      summary: List Profile Studio packages
      description: Lists creator-scoped, versioned BAMF Profile Studio packages. Package output removes private capture/provider provenance. Requires profile_packages:read.
      parameters:
      - name: creator_id
        in: query
        schema:
          type: string
      - name: include_archived
        in: query
        schema:
          type: boolean
          default: false
      - name: limit
        in: query
        schema:
          type: integer
          maximum: 100
      responses:
        '200':
          description: Profile packages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericListResponse'
      tags:
      - Profile Packages
      operationId: getProfilePackages
      x-operation-id-source: derived
    post:
      summary: Create a Profile Studio package
      description: Creates a versioned BAMF package after exact approval. Requires profile_packages:write and Idempotency-Key. This reversible record write does not apply or publish changes to LinkedIn.
      responses:
        '201':
          description: Profile package created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericDataResponse'
      tags:
      - Profile Packages
      operationId: postProfilePackages
      x-operation-id-source: derived
  /profile-packages/{profile_package_id}:
    get:
      summary: Get a Profile Studio package
      description: Returns one creator-authorized package with safe package fields only. Requires profile_packages:read. The response ETag is the exact optimistic-concurrency token required for a subsequent save.
      parameters:
      - name: profile_package_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Profile package
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericDataResponse'
      tags:
      - Profile Packages
      operationId: getProfilePackagesByProfilePackageId
      x-operation-id-source: derived
    patch:
      summary: Update a Profile Studio package
      description: Updates a versioned BAMF package after exact approval. Requires profile_packages:write, a stable Idempotency-Key, and the exact If-Match ETag returned by GET. The response contains a profile-package-save-receipt/v1 whose package ID, previous ETag, returned ETag, and non-live/reversible flags must be validated before treating the save as complete. It is reversible and never applies changes to LinkedIn.
      parameters:
      - name: profile_package_id
        in: path
        required: true
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 8
          maxLength: 200
      - name: If-Match
        in: header
        required: true
        description: Exact ETag returned by GET /profile-packages/{profile_package_id}.
        schema:
          type: string
      responses:
        '200':
          description: Profile package updated with a validated save receipt
          headers:
            ETag:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericDataResponse'
        '412':
          description: The package changed since the supplied ETag; refresh before retrying.
        '428':
          description: The If-Match version token is required.
      tags:
      - Profile Packages
      operationId: patchProfilePackagesByProfilePackageId
      x-operation-id-source: derived
  /profile-packages/{profile_package_id}/duplicate:
    post:
      summary: Duplicate a Profile Studio package
      description: Creates a draft variation of an authorized package. Requires profile_packages:write and Idempotency-Key. This never applies or publishes to LinkedIn.
      parameters:
      - name: profile_package_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Profile package duplicated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericDataResponse'
      tags:
      - Profile Packages
      operationId: postProfilePackagesByProfilePackageIdDuplicate
      x-operation-id-source: derived
  /profile-packages/{profile_package_id}/select:
    post:
      summary: Select a Profile Studio package
      description: Marks an authorized BAMF package selected after exact approval. Requires profile_packages:write and Idempotency-Key. Selection is reversible package metadata, not live LinkedIn application.
      parameters:
      - name: profile_package_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Profile package selected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericDataResponse'
      tags:
      - Profile Packages
      operationId: postProfilePackagesByProfilePackageIdSelect
      x-operation-id-source: derived
  /profile-packages/{profile_package_id}/archive:
    post:
      summary: Archive a Profile Studio package
      description: Archives an authorized package after exact approval. Requires profile_packages:write and Idempotency-Key. Archive is reversible through PATCH and never modifies LinkedIn.
      parameters:
      - name: profile_package_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Profile package archived
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericDataResponse'
      tags:
      - Profile Packages
      operationId: postProfilePackagesByProfilePackageIdArchive
      x-operation-id-source: derived
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            request_id:
              type: string
    GenericDataResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/JSONValue'
    JSONValue:
      description: Any JSON value returned by flexible workflow, analytics, context, or generation payloads.
    ProfileSnapshotIngestRequest:
      type: object
      additionalProperties: false
      required:
      - id
      - creator_id
      - source_profile_url
      - captured_at
      - validation_status
      - is_pre_bamf_capture
      - is_original_baseline
      - profile
      - assets
      - missing
      - provenance
      properties:
        id:
          type: string
          format: uuid
          description: Exact immutable source snapshot UUID; also serves as record-level idempotency identity.
        creator_id:
          type: string
          format: uuid
        source_profile_url:
          type: string
          format: uri
          description: HTTPS LinkedIn /in/ profile URL.
        captured_at:
          type: string
          format: date-time
        validation_status:
          type: string
          enum:
          - pending
          - partial
          - verified
          - failed
        is_pre_bamf_capture:
          type: boolean
        is_original_baseline:
          type: boolean
          description: Allowed only when validation_status is verified and is_pre_bamf_capture is true.
        supersedes_snapshot_id:
          type:
          - string
          - 'null'
          format: uuid
        profile:
          type: object
          additionalProperties: false
          properties:
            name:
              type:
              - string
              - 'null'
              maxLength: 240
            headline:
              type:
              - string
              - 'null'
              maxLength: 500
            about:
              type:
              - string
              - 'null'
              maxLength: 12000
            location:
              type:
              - string
              - 'null'
              maxLength: 500
            profile_url:
              type:
              - string
              - 'null'
              format: uri
            featured:
              type: array
              maxItems: 6
              items:
                type: object
                additionalProperties: false
                properties:
                  title:
                    type:
                    - string
                    - 'null'
                    maxLength: 500
                  description:
                    type:
                    - string
                    - 'null'
                    maxLength: 2000
                  url:
                    type:
                    - string
                    - 'null'
                    format: uri
        assets:
          type: object
          additionalProperties: false
          properties:
            full_page_screenshot:
              anyOf:
              - $ref: '#/components/schemas/ProfileSnapshotAsset'
              - type: 'null'
            photo:
              anyOf:
              - $ref: '#/components/schemas/ProfileSnapshotAsset'
              - type: 'null'
            banner:
              anyOf:
              - $ref: '#/components/schemas/ProfileSnapshotAsset'
              - type: 'null'
            featured:
              type: array
              maxItems: 6
              items:
                $ref: '#/components/schemas/ProfileSnapshotAsset'
        missing:
          type: array
          maxItems: 20
          items:
            type: object
            additionalProperties: false
            required:
            - field
            - reason
            properties:
              field:
                type: string
                maxLength: 80
              reason:
                type: string
                maxLength: 500
        provenance:
          type: object
          additionalProperties: false
          required:
          - capture_method
          - source_system
          - source_record_id
          properties:
            capture_method:
              type: string
              enum:
              - governed_browser
              - api
              - import
            source_system:
              type: string
              maxLength: 120
            source_record_id:
              type: string
              maxLength: 240
            source_content_hash:
              type:
              - string
              - 'null'
              pattern: ^[0-9a-fA-F]{64}$
              description: Source system's immutable custody hash. This is distinct from BAMF.ai's canonical content_hash.
            source_snapshot_id:
              type:
              - string
              - 'null'
              format: uuid
            capture_receipt_id:
              type:
              - string
              - 'null'
              format: uuid
            capture_job_id:
              type:
              - string
              - 'null'
              format: uuid
            visible_url:
              type:
              - string
              - 'null'
              format: uri
            evidence_refs:
              type: array
              maxItems: 12
              items:
                type: string
                maxLength: 500
            notes:
              type:
              - string
              - 'null'
              maxLength: 1000
        content_hash:
          type:
          - string
          - 'null'
          pattern: ^[0-9a-fA-F]{64}$
          description: Optional expected BAMF.ai canonical hash. Omit on first handoff and persist the returned hash for receipts.
    ProfileSnapshotIngestResponse:
      type: object
      required:
      - data
      properties:
        data:
          type: object
          required:
          - snapshot_id
          - creator_id
          - captured_at
          - validation_status
          - is_pre_bamf_capture
          - is_original_baseline
          - content_hash
          - created_at
          - idempotent_replay
          properties:
            snapshot_id:
              type: string
              format: uuid
            creator_id:
              type: string
              format: uuid
            captured_at:
              type: string
              format: date-time
            validation_status:
              type: string
              enum:
              - pending
              - partial
              - verified
              - failed
            is_pre_bamf_capture:
              type: boolean
            is_original_baseline:
              type: boolean
            content_hash:
              type: string
              pattern: ^[0-9a-f]{64}$
            created_at:
              type: string
              format: date-time
            idempotent_replay:
              type: boolean
    ProfileSnapshotAsset:
      type: object
      additionalProperties: false
      required:
      - asset_id
      - mime_type
      - size_bytes
      - sha256
      - localization_status
      properties:
        asset_id:
          type: string
          maxLength: 160
        storage_bucket:
          type:
          - string
          - 'null'
          maxLength: 160
          description: Optional durable bucket identifier. Omit for private cross-system storage.
        storage_path:
          type:
          - string
          - 'null'
          maxLength: 1000
          description: Optional relative object path. Signed URLs and credentials are forbidden.
        mime_type:
          type: string
          enum:
          - image/png
          - image/jpeg
          - image/webp
        size_bytes:
          type: integer
          minimum: 1
          maximum: 52428800
        sha256:
          type: string
          pattern: ^[0-9a-fA-F]{64}$
        source_url:
          type:
          - string
          - 'null'
          format: uri
          description: Credential-free public HTTPS URL; query and fragment are discarded.
        captured_at:
          type:
          - string
          - 'null'
          format: date-time
        localization_status:
          type: string
          enum:
          - localized
          - external
          - missing
    GenericListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/JSONValue'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer