Mydentify Public API Imports API

openapi: 3.2.0
info:
  title: Mydentify Public Imports API
  version: 1.4.0
  description: Read product directories and weekly leaderboard data or create a product. Public endpoints use HTTPS and need no API key. Directory JSON endpoints allow browser requests from any origin.
servers:
- url: https://mydentify.com
security: []
tags:
- name: Imports
paths:
  /api/imports/dry-run:
    post:
      summary: Inspect identity and duplicates without creating a product
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              properties:
                url:
                  type: string
                  format: uri
      responses:
        '200':
          description: Inspection result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DryRunResult'
        '422':
          $ref: '#/components/responses/ImportError'
        '503':
          $ref: '#/components/responses/ImportError'
      tags:
      - Imports
  /api/imports:
    post:
      summary: Create or reuse a durable product diagnostic or product import
      parameters:
      - in: header
        name: Idempotency-Key
        required: false
        schema:
          type: string
          minLength: 8
          maxLength: 200
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportRequest'
      responses:
        '200':
          description: Existing idempotent import
        '202':
          description: Import queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportAccepted'
        '409':
          $ref: '#/components/responses/ImportError'
      tags:
      - Imports
  /api/imports/{id}:
    get:
      summary: Get current import state, evidence candidates, warnings, duplicate resolution, and next action
      parameters:
      - $ref: '#/components/parameters/ImportId'
      responses:
        '200':
          description: Current import
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportStatus'
        '404':
          $ref: '#/components/responses/ImportError'
      tags:
      - Imports
  /api/imports/{id}/events:
    get:
      summary: Stream durable import events
      parameters:
      - $ref: '#/components/parameters/ImportId'
      - in: header
        name: Last-Event-ID
        schema:
          type: integer
      responses:
        '200':
          description: SSE stream
          content:
            text/event-stream: {}
      tags:
      - Imports
  /api/imports/{id}/retry:
    post:
      summary: Queue an allowed retry
      parameters:
      - $ref: '#/components/parameters/ImportId'
      responses:
        '202':
          description: Retry queued
        '409':
          $ref: '#/components/responses/ImportError'
        '429':
          $ref: '#/components/responses/ImportError'
      tags:
      - Imports
  /api/imports/{id}/manual-review:
    post:
      summary: Preserve a failed import and send it to editorial review
      parameters:
      - $ref: '#/components/parameters/ImportId'
      responses:
        '200':
          description: Manual review requested
        '404':
          $ref: '#/components/responses/ImportError'
        '409':
          $ref: '#/components/responses/ImportError'
      tags:
      - Imports
  /api/imports/{id}/goals:
    post:
      summary: Confirm evidence-backed intents and choose the publication path
      description: Free products must publish a followed link to https://mydentify.com/. The link may use text, a custom image, or the optional official badge from https://mydentify.com/badges/listed-on-mydentify.svg. A Player Pass publishes the product and enters the selected leaderboard after checkout or a free offer claim.
      parameters:
      - $ref: '#/components/parameters/ImportId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - intentIds
              properties:
                intentIds:
                  type: array
                  minItems: 1
                  maxItems: 3
                  uniqueItems: true
                  items:
                    type: string
                    format: uuid
                path:
                  type: string
                  enum:
                  - free
                  - player
                  default: free
      responses:
        '200':
          description: Intent selection saved and publication path prepared
        '400':
          $ref: '#/components/responses/ImportError'
        '409':
          $ref: '#/components/responses/ImportError'
      tags:
      - Imports
  /api/imports/{id}/verify-badge:
    post:
      summary: Recheck the required free-product backlink and publish when verified
      parameters:
      - $ref: '#/components/parameters/ImportId'
      responses:
        '200':
          description: Current backlink verification and publication state
        '403':
          $ref: '#/components/responses/ImportError'
        '404':
          $ref: '#/components/responses/ImportError'
        '409':
          $ref: '#/components/responses/ImportError'
      tags:
      - Imports
components:
  schemas:
    DuplicateResolution:
      type: object
      required:
      - classification
      - matchType
      - confidence
      - reason
      - claimed
      - product
      - proposedChanges
      - allowedActions
      properties:
        classification:
          type: string
          enum:
          - exact_duplicate
          - probable_duplicate
          - renamed_product
        matchType:
          type: string
          examples:
          - exact_url
          - known_url
          - external_github
          - domain_and_name
        confidence:
          type: number
          minimum: 0
          maximum: 1
        reason:
          type: string
        claimed:
          type: boolean
        product:
          $ref: '#/components/schemas/CanonicalProduct'
        proposedChanges:
          type: array
          items:
            type: object
            required:
            - field
            - proposed
            - sourceUrl
            properties:
              field:
                type: string
              current: {}
              proposed: {}
              sourceUrl:
                type: string
                format: uri
        allowedActions:
          type: array
          items:
            type: object
            required:
            - type
            - href
            properties:
              type:
                type: string
                enum:
                - view_existing
                - claim_product
                - restore_access
                - review_proposed_updates
              href:
                type: string
    Remediation:
      type: object
      required:
      - summary
      - actions
      properties:
        summary:
          type: string
        actions:
          type: array
          items:
            type: object
            required:
            - type
            - label
            - href
            properties:
              type:
                type: string
                enum:
                - retry
                - retry_after
                - try_another_url
                - manual_review
              label:
                type: string
              href:
                type: string
              retryAfter:
                type: string
                format: date-time
    ImportStatus:
      type: object
      required:
      - id
      - status
      - attemptCount
      - nextAction
      - stages
      - candidates
      - sourceFetches
      properties:
        id:
          type: string
          format: uuid
        mode:
          type: string
          enum:
          - diagnostic
          - listing
        status:
          type: string
          enum:
          - queued
          - running
          - needs_input
          - retry_scheduled
          - duplicate_detected
          - ready_for_confirmation
          - submitted_for_review
          - approved
          - rejected
          - failed
          - canceled
        attemptCount:
          type: integer
          minimum: 0
        nextAction:
          type: object
          additionalProperties: true
        remediation:
          anyOf:
          - $ref: '#/components/schemas/Remediation'
          - type: 'null'
        duplicate:
          anyOf:
          - $ref: '#/components/schemas/DuplicateResolution'
          - type: 'null'
        publication:
          anyOf:
          - $ref: '#/components/schemas/Publication'
          - type: 'null'
        rejection:
          anyOf:
          - $ref: '#/components/schemas/Rejection'
          - type: 'null'
        readinessReport:
          anyOf:
          - $ref: '#/components/schemas/ReadinessReport'
          - type: 'null'
        stages:
          type: array
          items:
            type: object
            additionalProperties: true
        candidates:
          type: array
          items:
            type: object
            additionalProperties: true
        sourceFetches:
          type: array
          items:
            type: object
            additionalProperties: true
        warnings:
          type: array
          items:
            type: object
            additionalProperties: true
    ImportAccepted:
      type: object
      required:
      - importId
      - status
      - statusUrl
      - eventsUrl
      - submittedAt
      - reused
      - nextAction
      properties:
        importId:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - queued
          - running
          - needs_input
          - retry_scheduled
          - duplicate_detected
          - ready_for_confirmation
          - submitted_for_review
          - approved
          - rejected
          - failed
          - canceled
        statusUrl:
          type: string
          format: uri
        eventsUrl:
          type: string
          format: uri
        submittedAt:
          type: string
          format: date-time
        reused:
          type: boolean
        nextAction:
          type: object
          additionalProperties: true
    CanonicalProduct:
      type: object
      required:
      - id
      - name
      - slug
      - status
      - url
      - humanUrl
      - jsonUrl
      - markdownUrl
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        slug:
          type: string
        status:
          type: string
        url:
          type: string
          format: uri
        humanUrl:
          type: string
          format: uri
        jsonUrl:
          type: string
          format: uri
        markdownUrl:
          type: string
          format: uri
    Rejection:
      type: object
      required:
      - category
      - message
      - correctionHint
      - publicNote
      properties:
        category:
          type: string
          enum:
          - identity_unclear
          - insufficient_public_evidence
          - unsupported_or_private_source
          - duplicate_listing
          - inaccurate_claims
          - unsafe_or_prohibited
        message:
          type: string
        correctionHint:
          type: string
        publicNote:
          type: string
    ImportRequest:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
        mode:
          type: string
          enum:
          - diagnostic
          - listing
          default: listing
        requestedIntentSlug:
          type: string
        source:
          type: string
          enum:
          - human
          - agent
          default: human
        submittedByAgent:
          type: string
          maxLength: 120
    ReadinessReport:
      type: object
      required:
      - rubricVersion
      - status
      - totalScore
      - confidence
      - summary
      - sourceCount
      - scannedAt
      - dimensions
      properties:
        rubricVersion:
          type: string
          examples:
          - readiness-v1
        status:
          type: string
          enum:
          - complete
          - partial
        totalScore:
          type: integer
          minimum: 0
          maximum: 100
        confidence:
          type: number
          minimum: 0
          maximum: 1
        summary:
          type: string
        sourceCount:
          type: integer
          minimum: 0
        scannedAt:
          type: string
          format: date-time
        dimensions:
          type: array
          minItems: 5
          maxItems: 5
          items:
            type: object
            required:
            - key
            - label
            - score
            - maxScore
            - summary
            - findings
            properties:
              key:
                type: string
                enum:
                - product_understood
                - intent_coverage
                - evidence_strength
                - agent_accessibility
                - recommendation_readiness
              label:
                type: string
              score:
                type: integer
                minimum: 0
                maximum: 20
              maxScore:
                const: 20
              summary:
                type: string
              findings:
                type: array
                items:
                  type: object
                  required:
                  - code
                  - label
                  - status
                  - score
                  - maxScore
                  - recommendation
                  - evidence
                  properties:
                    code:
                      type: string
                    label:
                      type: string
                    status:
                      type: string
                      enum:
                      - passed
                      - partial
                      - failed
                      - unavailable
                      - not_applicable
                    score:
                      type: number
                    maxScore:
                      type: number
                    recommendation:
                      type: string
                    evidence:
                      type: array
                      items:
                        type: object
                        additionalProperties: true
    DryRunResult:
      type: object
      required:
      - normalizedUrl
      - finalUrl
      - canonicalUrl
      - identity
      - discovered
      - nextAction
      properties:
        normalizedUrl:
          type: string
          format: uri
        finalUrl:
          type: string
          format: uri
        canonicalUrl:
          type: string
          format: uri
        identity:
          type: object
          additionalProperties: true
        duplicate:
          anyOf:
          - $ref: '#/components/schemas/DuplicateResolution'
          - type: 'null'
        discovered:
          type: object
          additionalProperties: true
        nextAction:
          type: object
          additionalProperties: true
    Publication:
      type: object
      required:
      - productId
      - humanUrl
      - jsonUrl
      - markdownUrl
      - supportedIntents
      properties:
        productId:
          type: string
          format: uuid
        humanUrl:
          type: string
          format: uri
        jsonUrl:
          type: string
          format: uri
        markdownUrl:
          type: string
          format: uri
        supportedIntents:
          type: array
          items:
            type: object
            required:
            - id
            - title
            - slug
            - humanUrl
            - jsonUrl
            - markdownUrl
            properties:
              id:
                type: string
                format: uuid
              title:
                type: string
              slug:
                type: string
              humanUrl:
                type: string
                format: uri
              jsonUrl:
                type: string
                format: uri
              markdownUrl:
                type: string
                format: uri
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - retryable
          properties:
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
            retryAfter:
              type: string
              format: date-time
  parameters:
    ImportId:
      in: path
      name: id
      required: true
      schema:
        type: string
        format: uuid
  responses:
    ImportError:
      description: Structured import error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
externalDocs:
  description: Use the Mydentify public API
  url: https://mydentify.com/developers
x-cors:
  description: Directory JSON endpoints allow browser requests from any origin.
  allowOrigins:
  - '*'