BAMF.ai Creator Spaces API

openapi: 3.2.0
info:
  title: BAMF Developer Platform Creator Spaces API
  version: 0.1.0
servers:
- url: https://api.bamf.ai/v1
security:
- BearerAuth: []
tags:
- name: Creator Spaces
paths:
  /creator-spaces:
    get:
      summary: List creator spaces
      description: Lists only creator spaces authorized through the caller's effective memberships. Use detail=summary for compact discovery. Omitting detail preserves the legacy full public projection.
      parameters:
      - name: detail
        in: query
        schema:
          type: string
          enum:
          - summary
          - full
          default: full
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: cursor
        in: query
        schema:
          type: string
          maxLength: 128
        description: Opaque next_cursor from the previous page.
      - name: offset
        in: query
        deprecated: true
        schema:
          type: integer
          minimum: 0
          maximum: 100000
          default: 0
        description: Legacy numeric pagination input. Prefer cursor.
      responses:
        '200':
          description: Creator spaces
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatorSpacesResponse'
        '400':
          description: Invalid cursor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Creator Spaces
      operationId: getCreatorSpaces
      x-operation-id-source: derived
  /creator-spaces/{creator_id}/icp-policy:
    parameters:
    - name: creator_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      summary: Read creator-owned criteria, separating AI draft and approved policy
      description: Requires creator_spaces:read and effective creator membership. Managed workspaces return their canonical agency policy reference. Source-only addition pending deployment.
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Creator policy envelope with head, draft, active, generation status, or managed reference
        '403':
          description: Creator access denied
      tags:
      - Creator Spaces
      operationId: getCreatorSpacesByCreatorIdIcpPolicy
      x-operation-id-source: derived
    post:
      summary: Edit, activate or opt out of creator criteria using a revision guard
      description: Requires knowledge:write and effective owner/manager approval role. Edits append drafts; only explicit activation changes active authority. Managed agency criteria cannot be edited here.
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - action
              - expected_revision
              properties:
                action:
                  type: string
                  enum:
                  - edit
                  - activate
                  - opt_out
                expected_revision:
                  type: integer
                  minimum: 0
                version_id:
                  type: string
                  format: uuid
                opted_out:
                  type: boolean
                criteria:
                  type: object
                  description: 'Canonical client-icp-policy/v2: schema plus target_roles, target_company_types, target_industries, target_locations, buyer_problems, required_criteria, positive_signals, disqualifiers, assumptions arrays. Required criteria must be exact positive criteria members.'
      responses:
        '200':
          description: Updated revision-guarded policy head
        '400':
          description: Invalid criteria/action
        '403':
          description: Approval permission denied
        '409':
          description: Stale revision or draft
      tags:
      - Creator Spaces
      operationId: postCreatorSpacesByCreatorIdIcpPolicy
      x-operation-id-source: derived
  /creator-spaces/{creator_id}/icp-generation-settings:
    post:
      summary: Configure a supported model for automatic creator criteria drafts
      description: Requires creator_spaces:write, creator access and exact workspace owner/admin membership. Missing settings leave configuration_required; no paid fallback model is selected. Managed agency workspaces reject native generation settings.
      security:
      - BearerAuth: []
      parameters:
      - name: creator_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - provider
              - model
              properties:
                provider:
                  type:
                  - string
                  - 'null'
                  enum:
                  - openai
                  - null
                model:
                  type:
                  - string
                  - 'null'
                  description: Canonical server-supported model; clear both fields with null.
      responses:
        '200':
          description: Saved owned workspace generation setting
        '400':
          description: Unsupported model or missing workspace
        '403':
          description: Workspace setting permission denied
        '409':
          description: Managed policy reference
      tags:
      - Creator Spaces
      operationId: postCreatorSpacesByCreatorIdIcpGenerationSettings
      x-operation-id-source: derived
  /creator-spaces/{creator_id}/context:
    get:
      summary: Get comprehensive creator context
      description: 'Returns the creator context bundle used by agents: knowledge docs, identity/context, AI analyses, voice profile, integrations, interviews, LinkedIn profile/posts/performance, website, website screenshot, brand kits, and media. Sections are scope-gated and omitted sections are reported.'
      parameters:
      - name: creator_id
        in: path
        required: true
        schema:
          type: string
      - name: sections
        in: query
        schema:
          type: string
        description: Comma-separated section names, or omit for all readable sections.
      - name: limit
        in: query
        schema:
          type: integer
          maximum: 100
      responses:
        '200':
          description: Creator context bundle
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatorContextResponse'
      tags:
      - Creator Spaces
      operationId: getCreatorSpacesByCreatorIdContext
      x-operation-id-source: derived
  /creator-spaces/{creator_id}/browser-session:
    get:
      summary: Get shared browser session
      description: Returns sanitized browser-connection metadata for account state only. V2 must not use this route to obtain, seed, or transfer browser credentials. Requires browser_session:read. Every read is audited.
      parameters:
      - name: creator_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Shared session found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserSessionResponse'
        '404':
          description: No shared session, or it was revoked
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: no_shared_session
      tags:
      - Creator Spaces
      operationId: getCreatorSpacesByCreatorIdBrowserSession
      x-operation-id-source: derived
    delete:
      summary: Revoke shared browser session
      description: Revokes the creator's browser connection server-side. Requires browser_session:read. Every revoke is audited.
      parameters:
      - name: creator_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Revoked
          content:
            application/json:
              schema:
                type: object
                properties:
                  revoked:
                    type: boolean
                    example: true
        '404':
          description: Already revoked or never shared
      tags:
      - Creator Spaces
      operationId: deleteCreatorSpacesByCreatorIdBrowserSession
      x-operation-id-source: derived
  /creator-spaces/{creator_id}:
    patch:
      summary: Update creator space settings
      description: Requires creator_spaces:write.
      parameters:
      - name: creator_id
        in: path
        required: true
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Updated creator space
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericDataResponse'
      tags:
      - Creator Spaces
      operationId: patchCreatorSpacesByCreatorId
      x-operation-id-source: derived
  /creator-spaces/{creator_id}/members:
    get:
      summary: List creator space members
      description: Requires members:read.
      parameters:
      - name: creator_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Members
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericListResponse'
      tags:
      - Creator Spaces
      operationId: getCreatorSpacesByCreatorIdMembers
      x-operation-id-source: derived
    post:
      summary: Add or update a creator space member
      description: Requires members:write. Upserts by user_id.
      parameters:
      - name: creator_id
        in: path
        required: true
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - user_id
              properties:
                user_id:
                  type: string
                role:
                  type: string
                  enum:
                  - owner
                  - manager
                  - member
                  - client
      responses:
        '200':
          description: Member record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericDataResponse'
      tags:
      - Creator Spaces
      operationId: postCreatorSpacesByCreatorIdMembers
      x-operation-id-source: derived
  /creator-spaces/{creator_id}/members/{user_id}:
    patch:
      summary: Update a creator space member's role
      description: Requires members:write. Only an owner can grant the owner role.
      parameters:
      - name: creator_id
        in: path
        required: true
        schema:
          type: string
      - name: user_id
        in: path
        required: true
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Updated member
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericDataResponse'
      tags:
      - Creator Spaces
      operationId: patchCreatorSpacesByCreatorIdMembersByUserId
      x-operation-id-source: derived
    delete:
      summary: Remove a creator space member
      description: Requires members:write.
      parameters:
      - name: creator_id
        in: path
        required: true
        schema:
          type: string
      - name: user_id
        in: path
        required: true
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Member removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericDataResponse'
      tags:
      - Creator Spaces
      operationId: deleteCreatorSpacesByCreatorIdMembersByUserId
      x-operation-id-source: derived
  /creator-spaces/{creator_id}/invitations:
    get:
      summary: List creator space invitations
      description: Requires members:write.
      parameters:
      - name: creator_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Invitations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericListResponse'
      tags:
      - Creator Spaces
      operationId: getCreatorSpacesByCreatorIdInvitations
      x-operation-id-source: derived
    post:
      summary: Invite a member to a creator space
      description: Requires members:write. Upserts a pending invitation by email; invitations expire after 7 days.
      parameters:
      - name: creator_id
        in: path
        required: true
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                role:
                  type: string
                  enum:
                  - owner
                  - manager
                  - member
                  - client
      responses:
        '200':
          description: Invitation record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericDataResponse'
        '409':
          description: Invitation already accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Creator Spaces
      operationId: postCreatorSpacesByCreatorIdInvitations
      x-operation-id-source: derived
  /creator-spaces/{creator_id}/invitations/{invitation_id}:
    delete:
      summary: Revoke a pending creator space invitation
      description: Requires members:write.
      parameters:
      - name: creator_id
        in: path
        required: true
        schema:
          type: string
      - name: invitation_id
        in: path
        required: true
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Invitation revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericDataResponse'
      tags:
      - Creator Spaces
      operationId: deleteCreatorSpacesByCreatorIdInvitationsByInvitationId
      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
    CreatorSpace:
      type: object
      properties:
        id:
          type: string
        creator_id:
          type: string
          description: Alias of id for agent workflows that ask for creator_id.
        user_id:
          type:
          - string
          - 'null'
        workspace_id:
          type:
          - string
          - 'null'
        name:
          type:
          - string
          - 'null'
        bio:
          type:
          - string
          - 'null'
        industry:
          type:
          - string
          - 'null'
        job_description:
          type:
          - string
          - 'null'
        avatar_url:
          type:
          - string
          - 'null'
        linkedin_username:
          type:
          - string
          - 'null'
        linkedin_headline:
          type:
          - string
          - 'null'
        linkedin_profile_url:
          type:
          - string
          - 'null'
        website_url:
          type:
          - string
          - 'null'
        website_summary:
          type:
          - string
          - 'null'
        follower_count:
          type:
          - integer
          - 'null'
          description: Current LinkedIn follower count from the linked profile metrics row.
        connection_count:
          type:
          - integer
          - 'null'
        profile_views:
          type:
          - integer
          - 'null'
        linkedin_profile:
          $ref: '#/components/schemas/LinkedInCreatorProfile'
        created_at:
          type:
          - string
          - 'null'
          format: date-time
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
    CreatorSpacesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CreatorSpace'
        pagination:
          type: object
          required:
          - limit
          - offset
          - returned
          - has_more
          - next_cursor
          properties:
            limit:
              type: integer
              minimum: 1
              maximum: 100
            offset:
              type: integer
              minimum: 0
              description: Legacy numeric position. New callers should use next_cursor.
            returned:
              type: integer
              minimum: 0
            has_more:
              type: boolean
            next_cursor:
              type:
              - string
              - 'null'
              description: Opaque cursor for the next page, or null on the final page.
    LinkedInCreatorProfile:
      type:
      - object
      - 'null'
      properties:
        id:
          type: string
        url:
          type:
          - string
          - 'null'
        name:
          type:
          - string
          - 'null'
        headline:
          type:
          - string
          - 'null'
        bio:
          type:
          - string
          - 'null'
        job_title:
          type:
          - string
          - 'null'
        company_name:
          type:
          - string
          - 'null'
        location:
          type:
          - string
          - 'null'
        profile_image_url:
          type:
          - string
          - 'null'
        follower_count:
          type:
          - integer
          - 'null'
        connection_count:
          type:
          - integer
          - 'null'
        profile_views:
          type:
          - integer
          - 'null'
        status:
          type:
          - string
          - 'null'
        last_refreshed:
          type:
          - string
          - 'null'
          format: date-time
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
    GenericDataResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/JSONValue'
    JSONValue:
      description: Any JSON value returned by flexible workflow, analytics, context, or generation payloads.
    BrowserSessionResponse:
      type: object
      properties:
        provider:
          type: string
          example: linkedin
        linkedin_url:
          type: string
          example: https://www.linkedin.com/in/bamfcreator
        shared_at:
          type: string
          format: date-time
        status:
          type: string
          example: connected
        cookies:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
                type: string
              domain:
                type: string
              path:
                type: string
              secure:
                type: boolean
              httpOnly:
                type: boolean
              sameSite:
                type: string
    CreatorContextResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            creator_id:
              type: string
            sections:
              type: array
              items:
                type: string
            omitted_sections:
              type: array
              items:
                type: object
                properties:
                  section:
                    type: string
                  required_scope:
                    type: string
            creator_space:
              $ref: '#/components/schemas/CreatorSpace'
            profile:
              $ref: '#/components/schemas/JSONValue'
            context:
              $ref: '#/components/schemas/JSONValue'
            voice_profile:
              $ref: '#/components/schemas/JSONValue'
            ai_analysis:
              $ref: '#/components/schemas/JSONValue'
            knowledge_docs:
              type: array
              items:
                $ref: '#/components/schemas/JSONValue'
            interviews:
              type: array
              items:
                $ref: '#/components/schemas/JSONValue'
            integrations:
              $ref: '#/components/schemas/JSONValue'
            linkedin_profile:
              $ref: '#/components/schemas/LinkedInCreatorProfile'
            linkedin_posts:
              type: array
              items:
                $ref: '#/components/schemas/JSONValue'
            linkedin_analytics:
              $ref: '#/components/schemas/JSONValue'
            x_profile:
              $ref: '#/components/schemas/JSONValue'
            x_posts:
              type: array
              items:
                $ref: '#/components/schemas/JSONValue'
            x_analytics:
              $ref: '#/components/schemas/JSONValue'
            website:
              $ref: '#/components/schemas/JSONValue'
            website_screenshot:
              $ref: '#/components/schemas/JSONValue'
            brand_kits:
              $ref: '#/components/schemas/JSONValue'
            media:
              type: array
              items:
                $ref: '#/components/schemas/JSONValue'
    GenericListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/JSONValue'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer