openapi: 3.1.0
info:
  title: CDP Public API
  version: 1.0.0
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  description: >
    Public REST API for the Community Data Platform (CDP). Provides transactional
    endpoints for identity verification, work experience management, project
    affiliations, and contributor lookup.


    Two authentication methods are supported depending on the endpoint:

    - **OAuth 2.0 Bearer (Auth0)** — used by LFX One for member, organization,
      and affiliation management endpoints.

    - **Static API Key** — bearer token with scopes managed in the CDP database.

servers:
  - url: https://cm.lfx.dev/api/v1
    description: Production
  - url: https://lf-staging.crowd.dev/api/v1
    description: Staging

security: []

tags:
  - name: Members
    description: Resolve member profiles by identity.
  - name: Member Identities
    description: Manage and verify member identities across platforms.
  - name: Maintainer Roles
    description: Retrieve maintainer roles for a member.
  - name: Work Experiences
    description: Manage and verify member work experiences (organization affiliations).
  - name: Project Affiliations
    description: View and override per-project affiliation data for a member.
  - name: Organizations
    description: Look up and create organizations.
  - name: Affiliations
    description: Bulk contributor affiliation lookups by GitHub handle.

paths:
  # ──────────────────────────────────────────────
  # Members
  # ──────────────────────────────────────────────
  /members:
    post:
      operationId: createMember
      summary: Create a member profile
      description: >
        Create a new member profile in CDP with one or more identities.
      tags:
        - Members
      security:
        - OAuth2Bearer:
            - write:members
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - displayName
                - identities
              properties:
                displayName:
                  type: string
                  minLength: 1
                  description: Display name for the member profile.
                identities:
                  type: array
                  minItems: 1
                  description: Initial identities for the member.
                  items:
                    $ref: '#/components/schemas/MemberIdentityInput'
            example:
              displayName: Jane Doe
              identities:
                - value: abc123
                  platform: lfid
                  type: username
                  source: lfxOne
                  verified: true
                  verifiedBy: jane@lfx.dev
      responses:
        '201':
          description: Member created successfully.
          content:
            application/json:
              schema:
                type: object
                required:
                  - memberId
                properties:
                  memberId:
                    type: string
                    format: uuid
              example:
                memberId: 550e8400-e29b-41d4-a716-446655440000
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: Identity already exists on another member.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
              example:
                error:
                  code: CONFLICT
                  message: Identity already exists on another member

  /members/resolve:
    post:
      operationId: resolveMember
      summary: Resolve a CDP member profile
      description: >
        Resolve memberId from identities. LFX One should always make a first
        request to this API to retrieve the corresponding memberId from CDP.
        If a member is found, use it. If not, create a member.
      tags:
        - Members
      security:
        - OAuth2Bearer:
            - read:members
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - lfids
              properties:
                lfids:
                  type: array
                  description: LFX IDs to search for.
                  minItems: 1
                  items:
                    type: string
                    minLength: 1
                emails:
                  type: array
                  description: Optional email addresses to include in the lookup.
                  items:
                    type: string
                    format: email
            example:
              lfids:
                - abc123
              emails:
                - user@example.com
      responses:
        '200':
          description: Member resolved successfully.
          content:
            application/json:
              schema:
                type: object
                required:
                  - memberId
                properties:
                  memberId:
                    type: string
                    format: uuid
              example:
                memberId: 550e8400-e29b-41d4-a716-446655440000
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Profile not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
              example:
                error:
                  code: NOT_FOUND
                  message: Member not found
        '409':
          description: Multiple member profiles matched.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
              example:
                error:
                  code: CONFLICT
                  message: Multiple member profiles matched

  # ──────────────────────────────────────────────
  # Member Identities
  # ──────────────────────────────────────────────
  /members/{memberId}/identities:
    get:
      operationId: getMemberIdentities
      summary: List member identities
      description: Retrieve all identities for a member profile.
      tags:
        - Member Identities
      security:
        - OAuth2Bearer:
            - read:member-identities
      parameters:
        - $ref: '#/components/parameters/MemberId'
      responses:
        '200':
          description: Identities retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                required:
                  - identities
                properties:
                  identities:
                    type: array
                    items:
                      $ref: '#/components/schemas/MemberIdentity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/MemberNotFound'

    post:
      operationId: createMemberIdentity
      summary: Add a new identity
      description: >
        Add a new identity to a member profile. Returns 409 if the identity
        already exists on this member or is verified on another member.
      tags:
        - Member Identities
      security:
        - OAuth2Bearer:
            - write:member-identities
      parameters:
        - $ref: '#/components/parameters/MemberId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - value
                - platform
                - type
                - source
                - verified
              properties:
                value:
                  type: string
                  minLength: 1
                  description: Identity value (e.g. username, email address).
                platform:
                  type: string
                  minLength: 1
                  description: Platform name (e.g. github, linkedin).
                type:
                  type: string
                  enum:
                    - username
                    - email
                  description: Identity type.
                source:
                  type: string
                  minLength: 1
                  description: Source system that created this identity.
                verified:
                  type: boolean
                  description: Whether the identity is verified.
                verifiedBy:
                  type: string
                  description: Required when `verified` is true. Identifier of who verified.
            example:
              value: johndoe
              platform: github
              type: username
              source: lfxOne
              verified: true
              verifiedBy: admin@lfx.dev
      responses:
        '201':
          description: Identity created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberIdentity'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/MemberNotFound'
        '409':
          description: Identity already exists on another member.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
              example:
                error:
                  code: CONFLICT
                  message: Identity already exists on another member

  /members/{memberId}/identities/{identityId}:
    patch:
      operationId: verifyMemberIdentity
      summary: Verify or reject an identity
      description: >
        Set an identity as verified or rejected. When rejected (`verified: false`),
        the identity is either soft-deleted (no linked activities) or unmerged to
        a new profile (has linked activities).
      tags:
        - Member Identities
      security:
        - OAuth2Bearer:
            - write:member-identities
      parameters:
        - $ref: '#/components/parameters/MemberId'
        - name: identityId
          in: path
          required: true
          description: UUID of the identity to verify or reject.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - verified
                - verifiedBy
              properties:
                verified:
                  type: boolean
                  description: >
                    `true` to verify the identity, `false` to reject it.
                verifiedBy:
                  type: string
                  description: Identifier of who performed the verification.
            example:
              verified: true
              verifiedBy: admin@lfx.dev
      responses:
        '200':
          description: >
            Identity updated. Returned when verifying, or when rejecting an
            identity that has linked activities (triggers unmerge).
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/MemberIdentity'
                  - type: object
                    properties:
                      unmergedToMemberId:
                        type: string
                        format: uuid
                        description: >
                          Present only when rejection triggered an unmerge. The
                          new member profile ID that the identity was moved to.
        '204':
          description: >
            Identity rejected and deleted (no linked activities). No response body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Member or identity not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '409':
          description: Identity already exists on another member.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
              example:
                error:
                  code: CONFLICT
                  message: Identity already exists on another member

  # ──────────────────────────────────────────────
  # Maintainer Roles
  # ──────────────────────────────────────────────
  /members/{memberId}/maintainer-roles:
    get:
      operationId: getMemberMaintainerRoles
      summary: List maintainer roles
      description: Retrieve all maintainer roles for a member across projects.
      tags:
        - Maintainer Roles
      security:
        - OAuth2Bearer:
            - read:maintainer-roles
      parameters:
        - $ref: '#/components/parameters/MemberId'
      responses:
        '200':
          description: Maintainer roles retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                required:
                  - maintainerRoles
                properties:
                  maintainerRoles:
                    type: array
                    items:
                      $ref: '#/components/schemas/MaintainerRole'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/MemberNotFound'

  # ──────────────────────────────────────────────
  # Work Experiences
  # ──────────────────────────────────────────────
  /members/{memberId}/work-experiences:
    get:
      operationId: getMemberWorkExperiences
      summary: List work experiences
      description: Retrieve all work experiences for a member.
      tags:
        - Work Experiences
      security:
        - OAuth2Bearer:
            - read:work-experiences
      parameters:
        - $ref: '#/components/parameters/MemberId'
      responses:
        '200':
          description: Work experiences retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                required:
                  - memberId
                  - workExperiences
                properties:
                  memberId:
                    type: string
                    format: uuid
                  workExperiences:
                    type: array
                    items:
                      $ref: '#/components/schemas/WorkExperience'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/MemberNotFound'

    post:
      operationId: createMemberWorkExperience
      summary: Add a work experience
      description: >
        Add a new work experience to a member profile. Returns 409 if a work
        experience with the same dates already exists.
      tags:
        - Work Experiences
      security:
        - OAuth2Bearer:
            - write:work-experiences
      parameters:
        - $ref: '#/components/parameters/MemberId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkExperienceInput'
            example:
              organizationId: 550e8400-e29b-41d4-a716-446655440000
              jobTitle: Senior Engineer
              verified: true
              verifiedBy: admin@lfx.dev
              source: lfxOne
              startDate: '2020-01-01T00:00:00.000Z'
              endDate: null
      responses:
        '201':
          description: Work experience created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkExperience'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/MemberNotFound'
        '409':
          description: A work experience with the same dates already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
              example:
                error:
                  code: CONFLICT
                  message: A work experience with the same dates already exists

  /members/{memberId}/work-experiences/{workExperienceId}:
    put:
      operationId: updateMemberWorkExperience
      summary: Update a work experience
      description: Replace all fields of an existing work experience.
      tags:
        - Work Experiences
      security:
        - OAuth2Bearer:
            - write:work-experiences
      parameters:
        - $ref: '#/components/parameters/MemberId'
        - $ref: '#/components/parameters/WorkExperienceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkExperienceInput'
      responses:
        '200':
          description: Work experience updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkExperience'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Member or work experience not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'

    patch:
      operationId: verifyMemberWorkExperience
      summary: Verify or reject a work experience
      description: >
        Set a work experience as verified or rejected. When rejected
        (`verified: false`), the work experience is soft-deleted and
        affiliations are recalculated.
      tags:
        - Work Experiences
      security:
        - OAuth2Bearer:
            - write:work-experiences
      parameters:
        - $ref: '#/components/parameters/MemberId'
        - $ref: '#/components/parameters/WorkExperienceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - verified
                - verifiedBy
              properties:
                verified:
                  type: boolean
                  description: >
                    `true` to verify, `false` to reject (soft-delete).
                verifiedBy:
                  type: string
                  description: Identifier of who performed the verification.
            example:
              verified: true
              verifiedBy: admin@lfx.dev
      responses:
        '200':
          description: Work experience updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkExperience'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Member or work experience not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'

    delete:
      operationId: deleteMemberWorkExperience
      summary: Delete a work experience
      description: >
        Soft-delete a work experience from a member profile. Affiliations are
        automatically recalculated.
      tags:
        - Work Experiences
      security:
        - OAuth2Bearer:
            - write:work-experiences
      parameters:
        - $ref: '#/components/parameters/MemberId'
        - $ref: '#/components/parameters/WorkExperienceId'
      responses:
        '204':
          description: Work experience deleted. No response body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Member or work experience not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'

  # ──────────────────────────────────────────────
  # Project Affiliations
  # ──────────────────────────────────────────────
  /members/{memberId}/project-affiliations:
    get:
      operationId: getMemberProjectAffiliations
      summary: List project affiliations
      description: >
        Retrieve per-project affiliation data for a member, including maintainer
        roles and resolved affiliations. Affiliations come from project-level
        overrides when available, otherwise from work experiences.
      tags:
        - Project Affiliations
      security:
        - OAuth2Bearer:
            - read:project-affiliations
      parameters:
        - $ref: '#/components/parameters/MemberId'
      responses:
        '200':
          description: Project affiliations retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                required:
                  - projectAffiliations
                properties:
                  projectAffiliations:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectAffiliation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/MemberNotFound'

  /members/{memberId}/project-affiliations/{projectId}:
    patch:
      operationId: patchMemberProjectAffiliation
      summary: Override project affiliations
      description: >
        Replace all project-level affiliation overrides for a member on a
        specific project. Pass an empty `affiliations` array to clear overrides
        (falling back to work experience-based affiliations).
      tags:
        - Project Affiliations
      security:
        - OAuth2Bearer:
            - write:project-affiliations
      parameters:
        - $ref: '#/components/parameters/MemberId'
        - name: projectId
          in: path
          required: true
          description: UUID of the project (segment ID).
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - affiliations
              properties:
                affiliations:
                  type: array
                  description: >
                    Affiliation overrides. Pass an empty array to clear.
                  items:
                    type: object
                    required:
                      - organizationId
                      - dateStart
                    properties:
                      organizationId:
                        type: string
                        format: uuid
                      dateStart:
                        type: string
                        format: date-time
                        description: Start date of the affiliation period.
                      dateEnd:
                        type:
                          - string
                          - 'null'
                        format: date-time
                        description: End date, or null if currently active.
                verifiedBy:
                  type: string
                  maxLength: 255
                  description: Required when `affiliations` is non-empty.
            example:
              affiliations:
                - organizationId: 550e8400-e29b-41d4-a716-446655440000
                  dateStart: '2020-01-01T00:00:00.000Z'
                  dateEnd: null
              verifiedBy: admin@lfx.dev
      responses:
        '200':
          description: Project affiliations updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectAffiliation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Member or project not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'

  # ──────────────────────────────────────────────
  # Organizations
  # ──────────────────────────────────────────────
  /organizations:
    get:
      operationId: getOrganization
      summary: Look up an organization by domain or name
      description: >
        Provide domain, name, or both. When both are provided, the domain and
        name must belong to the same organization. If multiple organizations
        match, the most active one is returned.
      tags:
        - Organizations
      security:
        - OAuth2Bearer:
            - read:organizations
      parameters:
        - name: domain
          in: query
          required: false
          description: Primary domain of the organization.
          schema:
            type: string
            minLength: 1
          example: linuxfoundation.org
        - name: name
          in: query
          required: false
          description: Exact display name of the organization.
          schema:
            type: string
            minLength: 1
          example: Linux Foundation
      responses:
        '200':
          description: Organization found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
              example:
                id: 550e8400-e29b-41d4-a716-446655440000
                name: Linux Foundation
                domain: linuxfoundation.org
                logo: https://example.com/logo.png
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: No organization found for the given domain or name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
              example:
                error:
                  code: NOT_FOUND
                  message: Organization not found

    post:
      operationId: createOrganization
      summary: Create an organization
      description: >
        Create a new organization with a verified primary domain. If an
        organization with the same domain already exists, it returns the
        existing one.
      tags:
        - Organizations
      security:
        - OAuth2Bearer:
            - write:organizations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - domain
                - source
              properties:
                name:
                  type: string
                  minLength: 1
                  description: Display name of the organization.
                domain:
                  type: string
                  minLength: 1
                  description: Primary domain of the organization.
                source:
                  type: string
                  minLength: 1
                  description: Source system creating the organization.
                logo:
                  type: string
                  format: uri
                  description: Optional URL of the organization's logo.
            example:
              name: Acme Corp
              domain: acme.com
              source: lfxOne
              logo: https://example.com/logo.png
      responses:
        '201':
          description: Organization created (or existing one returned).
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                  - name
                  - domain
                properties:
                  id:
                    type: string
                    format: uuid
                  name:
                    type: string
                  domain:
                    type: string
                    description: Verified primary domain of the organization.
                  logo:
                    type:
                      - string
                      - 'null'
                    description: URL of the organization logo.
              example:
                id: 550e8400-e29b-41d4-a716-446655440000
                name: Acme Corp
                domain: acme.com
                logo: https://example.com/logo.png
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  # ──────────────────────────────────────────────
  # Affiliations (Static API Key)
  # ──────────────────────────────────────────────
  /affiliations:
    post:
      operationId: getBulkAffiliations
      summary: Bulk contributor lookup
      description: >
        Look up affiliation data for up to 100 GitHub handles in a single
        request. Handles that have no matching LFX profile are returned in the
        `notFound` array.
      tags:
        - Affiliations
      security:
        - StaticApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - githubHandles
              properties:
                githubHandles:
                  type: array
                  description: >
                    List of GitHub login handles to look up (case-insensitive).
                  minItems: 1
                  maxItems: 100
                  items:
                    type: string
                    minLength: 1
            example:
              githubHandles:
                - torvalds
                - gvanrossum
      parameters:
        - name: page
          in: query
          description: Page number (1-based).
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: pageSize
          in: query
          description: Number of contributors to return per page.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Affiliations resolved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkAffiliationsResponse'
              example:
                total: 2
                totalFound: 2
                page: 1
                pageSize: 20
                contributorsInPage: 2
                contributors:
                  - githubHandle: torvalds
                    name: Linus Torvalds
                    emails:
                      - torvalds@linux-foundation.org
                    affiliations:
                      - organization: Linux Foundation
                        startDate: '2007-01-01T00:00:00.000Z'
                        endDate: null
                notFound: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /affiliations/{githubHandle}:
    get:
      operationId: getAffiliationByHandle
      summary: Single contributor lookup
      description: >
        Look up affiliation data for one developer by GitHub handle. Useful for
        debugging and ad-hoc queries.
      tags:
        - Affiliations
      security:
        - StaticApiKey: []
      parameters:
        - name: githubHandle
          in: path
          required: true
          description: GitHub login handle (case-insensitive).
          schema:
            type: string
            minLength: 1
          example: torvalds
      responses:
        '200':
          description: Developer found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contributor'
              example:
                githubHandle: torvalds
                name: Linus Torvalds
                emails:
                  - torvalds@linux-foundation.org
                affiliations:
                  - organization: Linux Foundation
                    startDate: '2007-01-01T00:00:00.000Z'
                    endDate: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: No LFX profile found for the given GitHub handle.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
              example:
                error:
                  code: NOT_FOUND
                  message: "No LFX profile found for GitHub login 'nonexistent-user'."
        '429':
          $ref: '#/components/responses/TooManyRequests'

components:
  securitySchemes:
    OAuth2Bearer:
      type: oauth2
      description: >
        OAuth 2.0 client credentials flow via Auth0. The consuming service
        obtains a JWT using its client ID and secret, then passes it as
        `Authorization: Bearer <token>`
      flows:
        clientCredentials:
          tokenUrl: https://linuxfoundation.auth0.com/oauth/token
          scopes:
            read:members: Read member profiles
            write:members: Create member profiles
            read:member-identities: Read member identities
            write:member-identities: Create and verify member identities
            read:maintainer-roles: Read maintainer roles
            read:work-experiences: Read work experiences
            write:work-experiences: Create, update, verify, and delete work experiences
            read:project-affiliations: Read project affiliations
            write:project-affiliations: Override project affiliations
            read:organizations: Look up organizations
            write:organizations: Create organizations
    StaticApiKey:
      type: http
      scheme: bearer
      description: >
        Static API key — pass as `Authorization: Bearer <token>`. Keys are
        managed in the CDP database with SHA-256 hashing, expiration, and
        revocation support.

  parameters:
    MemberId:
      name: memberId
      in: path
      required: true
      description: UUID of the member.
      schema:
        type: string
        format: uuid
    WorkExperienceId:
      name: workExperienceId
      in: path
      required: true
      description: UUID of the work experience.
      schema:
        type: string
        format: uuid

  schemas:
    MemberIdentityInput:
      type: object
      required:
        - value
        - platform
        - type
        - source
        - verified
      properties:
        value:
          type: string
          minLength: 1
          description: Identity value (e.g. username, email address).
        platform:
          type: string
          minLength: 1
          description: Platform name (e.g. github, lfid).
        type:
          type: string
          enum:
            - username
            - email
          description: Identity type.
        source:
          type: string
          minLength: 1
          description: Source system that created this identity.
        verified:
          type: boolean
          description: Whether the identity is verified.
        verifiedBy:
          type: string
          description: Required when `verified` is true. Identifier of who verified.

    MemberIdentity:
      type: object
      required:
        - id
        - value
        - platform
        - type
        - verified
        - verifiedBy
        - source
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
        value:
          type: string
          description: Identity value (username or email).
        platform:
          type: string
          description: Platform name (e.g. github, linkedin, lfid).
        type:
          type: string
          enum:
            - username
            - email
          description: Identity type.
        verified:
          type: boolean
        verifiedBy:
          type:
            - string
            - 'null'
          description: Identifier of who verified this identity, or null.
        source:
          type:
            - string
            - 'null'
          description: Source system that created this identity.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    MaintainerRole:
      type: object
      required:
        - id
        - memberId
        - segmentId
        - role
        - url
        - repoType
      properties:
        id:
          type: string
          format: uuid
        memberId:
          type: string
          format: uuid
        segmentId:
          type: string
          format: uuid
        dateStart:
          type:
            - string
            - 'null'
          format: date
          description: Start date of the maintainer role.
        dateEnd:
          type:
            - string
            - 'null'
          format: date
          description: End date of the maintainer role, or null if current.
        url:
          type: string
          description: Repository URL.
        repoType:
          type: string
          enum:
            - github
            - gitlab
            - git
            - gerrit
          description: Repository platform type.
        role:
          type: string
          description: Role name (e.g. maintainer, committer).
        maintainerFile:
          type:
            - string
            - 'null'
          description: Path to the maintainer file in the repository, if applicable.

    WorkExperience:
      type: object
      required:
        - id
        - organizationId
        - organizationName
        - organizationDomains
        - jobTitle
        - verified
        - verifiedBy
        - source
        - startDate
        - endDate
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
        organizationId:
          type: string
          format: uuid
        organizationName:
          type:
            - string
            - 'null'
          description: Display name of the organization.
        organizationLogo:
          type:
            - string
            - 'null'
          description: URL of the organization logo.
        organizationDomains:
          type: array
          items:
            type: string
          description: Verified primary domains for the organization, in alphabetical order.
        jobTitle:
          type:
            - string
            - 'null'
        verified:
          type: boolean
        verifiedBy:
          type:
            - string
            - 'null'
        source:
          type:
            - string
            - 'null'
          description: Source system that created this work experience.
        startDate:
          type:
            - string
            - 'null'
          format: date-time
        endDate:
          type:
            - string
            - 'null'
          format: date-time
          description: End date, or null if currently active.
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
        updatedAt:
          type:
            - string
            - 'null'
          format: date-time

    WorkExperienceInput:
      type: object
      required:
        - organizationId
        - jobTitle
        - verified
        - verifiedBy
        - source
        - startDate
      properties:
        organizationId:
          type: string
          format: uuid
        jobTitle:
          type: string
          description: Job title at the organization.
        verified:
          type: boolean
        verifiedBy:
          type: string
          description: Identifier of who verified this work experience.
        source:
          type: string
          description: Source system (e.g. lfxOne).
        startDate:
          type: string
          format: date-time
          description: Start date of the work experience.
        endDate:
          type:
            - string
            - 'null'
          format: date-time
          description: End date, or null if currently active.

    ProjectAffiliation:
      type: object
      required:
        - id
        - projectSlug
        - projectName
        - projectLogo
        - contributionCount
        - roles
        - affiliations
      properties:
        id:
          type: string
          format: uuid
          description: Segment (project) ID.
        projectSlug:
          type: string
        projectName:
          type: string
        projectLogo:
          type:
            - string
            - 'null'
        contributionCount:
          type: integer
          description: Total number of contributions in this project.
        roles:
          type: array
          items:
            $ref: '#/components/schemas/ProjectRole'
        affiliations:
          type: array
          items:
            $ref: '#/components/schemas/ProjectAffiliationEntry'

    ProjectRole:
      type: object
      required:
        - id
        - role
        - startDate
        - endDate
        - repoUrl
        - repoFileUrl
      properties:
        id:
          type: string
          format: uuid
        role:
          type: string
        startDate:
          type:
            - string
            - 'null'
          format: date-time
        endDate:
          type:
            - string
            - 'null'
          format: date-time
        repoUrl:
          type:
            - string
            - 'null'
        repoFileUrl:
          type:
            - string
            - 'null'

    ProjectAffiliationEntry:
      type: object
      required:
        - id
        - organizationId
        - organizationName
        - organizationLogo
        - verified
        - verifiedBy
        - startDate
        - endDate
        - type
      properties:
        id:
          type: string
          format: uuid
        organizationId:
          type: string
          format: uuid
        organizationName:
          type: string
        organizationLogo:
          type:
            - string
            - 'null'
        verified:
          type: boolean
        verifiedBy:
          type:
            - string
            - 'null'
        startDate:
          type:
            - string
            - 'null'
          format: date-time
        endDate:
          type:
            - string
            - 'null'
          format: date-time
        type:
          type: string
          enum:
            - project
            - work-history
          description: >
            `project` — manually overridden at the project level.
            `work-history` — derived from work experiences.
        source:
          type:
            - string
            - 'null'
          description: Present only for `work-history` type affiliations.

    AffiliationPeriod:
      type: object
      required:
        - organization
        - startDate
        - endDate
      properties:
        organization:
          type: string
          description: Name of the organization.
        startDate:
          type:
            - string
            - 'null'
          format: date-time
          description: Start date of the affiliation period.
        endDate:
          type:
            - string
            - 'null'
          format: date-time
          description: End date, or null if currently active.

    Contributor:
      type: object
      required:
        - githubHandle
        - name
        - emails
        - affiliations
      properties:
        githubHandle:
          type: string
          description: Verified GitHub login handle.
        name:
          type:
            - string
            - 'null'
          description: Display name from the LFX profile.
        emails:
          type: array
          description: Verified email addresses linked to the profile.
          items:
            type: string
            format: email
        affiliations:
          type: array
          description: Resolved affiliation periods, most recent first.
          items:
            $ref: '#/components/schemas/AffiliationPeriod'

    BulkAffiliationsResponse:
      type: object
      required:
        - total
        - totalFound
        - page
        - pageSize
        - contributorsInPage
        - contributors
        - notFound
      properties:
        total:
          type: integer
          description: Total number of handles submitted in the request.
        totalFound:
          type: integer
          description: Number of handles that matched an LFX profile.
        page:
          type: integer
          description: Current page number.
        pageSize:
          type: integer
          description: Maximum contributors per page.
        contributorsInPage:
          type: integer
          description: Number of contributors returned in this page.
        contributors:
          type: array
          items:
            $ref: '#/components/schemas/Contributor'
        notFound:
          type: array
          description: Handles from the request with no matching LFX profile.
          items:
            type: string

    Organization:
      type: object
      required:
        - id
        - name
        - domain
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          description: Display name of the organization.
        domain:
          type: string
          description: Verified primary domain.
        logo:
          type: string
          description: URL of the organization logo. Only present if available.

    HttpError:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Machine-readable error code.
            message:
              type: string
              description: Human-readable error description.

  responses:
    BadRequest:
      description: Invalid request body or query parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
          example:
            error:
              code: BAD_REQUEST
              message: Validation failed

    Unauthorized:
      description: Missing or invalid authentication credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
          example:
            error:
              code: UNAUTHORIZED
              message: Invalid or missing authentication

    Forbidden:
      description: Authentication valid but insufficient scopes.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
          example:
            error:
              code: INSUFFICIENT_SCOPE
              message: Insufficient scope for this operation

    MemberNotFound:
      description: No member found with the given ID.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
          example:
            error:
              code: NOT_FOUND
              message: Member not found

    TooManyRequests:
      description: Rate limit exceeded (60 requests per 60 seconds).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
          example:
            error:
              code: RATE_LIMITED
              message: Too many requests, please try again later