openapi: 3.2.0
info:
  title: ViewsMeet machine participation Personality API
  version: 0.5.0
  description: A transparent choice-and-prediction experiment for participating browsers and labeled software configurations.
servers:
- url: https://viewsmeet.com
tags:
- name: Personality
paths:
  /api/v1/personality/instrument:
    get:
      operationId: getMiniIpipPersonalityInstrument
      summary: Read the exact public-domain Mini-IPIP 20 instrument
      description: Returns the fixed 20 statement identifiers and wording plus the five response labels. Display order may vary in a client; wording and scoring do not.
      responses:
        '200':
          description: Exact versioned instrument and methodology URL
      tags:
      - Personality
  /api/v1/personality/score:
    post:
      operationId: scoreMiniIpipPersonalityResponses
      summary: Score one complete Mini-IPIP response vector without storing it
      description: Returns five deterministic raw response-scale means only. For software, the output describes the submitted vector; it does not establish an agent personality, identity, consciousness, diagnosis, type, percentile, or compatibility result.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - answers
              properties:
                answers:
                  type: array
                  minItems: 20
                  maxItems: 20
                  items:
                    type: object
                    additionalProperties: false
                    required:
                    - itemId
                    - response
                    properties:
                      itemId:
                        type: string
                        pattern: ^mini-ipip-(?:0[1-9]|1[0-9]|20)$
                      response:
                        type: integer
                        enum:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
      responses:
        '200':
          description: Five raw sums and means; the answer vector was not written to ViewsMeet storage
        '400':
          description: Incomplete, duplicate, extended, or invalid response vector
        '429':
          description: Rate limited
      tags:
      - Personality
  /api/v1/personality/methodology:
    get:
      operationId: getMiniIpipMethodology
      summary: Read instrument sources, scoring, reliability evidence, and limits
      responses:
        '200':
          description: Inspectable Mini-IPIP methodology metadata
      tags:
      - Personality
  /api/v1/personality/challenges:
    post:
      operationId: createPersonalityPerceptionChallenge
      summary: Create a seven-day private personality perception challenge
      description: Scores the exact Mini-IPIP self-response vector, immediately discards the 20 item responses, and stores only five keyed raw sums plus an optional bounded alias. This is not a public cohort or compatibility test.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - answers
              properties:
                answers:
                  $ref: '#/components/schemas/MiniIpipResponseVector'
                alias:
                  type: string
                  maxLength: 24
                sourceChallengeCode:
                  type: string
                  pattern: ^[A-Za-z0-9_-]{20,32}$
      responses:
        '201':
          description: Private capability link and management token; no item responses echoed or stored
        '400':
          description: Invalid or incomplete self-response vector
        '429':
          description: Rate limited
      tags:
      - Personality
  /api/v1/personality/challenges/{code}:
    get:
      operationId: getPersonalityPerceptionChallenge
      summary: Read one explicitly supplied private perception challenge
      description: Returns exact item text and response labels without creator answers or factor sums. Challenge enumeration is not available.
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{20,32}$
      responses:
        '200':
          description: Private challenge prompt with zero creator response data
        '410':
          description: Challenge expired, deleted, or unavailable
      tags:
      - Personality
  /api/v1/personality/challenges/{code}/perceptions:
    post:
      operationId: submitPersonalityPerception
      summary: Commit one prediction vector and receive five aggregate factor gaps
      description: The 20 predictions are scored and immediately discarded. Only five predicted keyed sums, a server-assigned transport, and an optional bounded alias are stored. The result has no item matches, overall accuracy, rank, type, percentile, diagnosis, or compatibility verdict.
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{20,32}$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - predictions
              - participantKey
              properties:
                predictions:
                  $ref: '#/components/schemas/MiniIpipResponseVector'
                participantKey:
                  type: string
                  pattern: ^[A-Za-z0-9_-]{16,128}$
                alias:
                  type: string
                  maxLength: 24
      responses:
        '201':
          description: Five aggregate creator-versus-prediction factor pairs and a deletion capability
        '400':
          description: Invalid, incomplete, or extended prediction vector
        '409':
          description: Duplicate participant or full challenge
        '410':
          description: Challenge closed
      tags:
      - Personality
  /api/v1/personality/perceptions/{token}:
    get:
      operationId: getPersonalityPerceptionResult
      summary: Rehydrate one aggregate-only result using its private capability
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{20,256}$
      responses:
        '200':
          description: Five aggregate factor pairs only
        '404':
          description: Capability invalid or expired
      tags:
      - Personality
    delete:
      operationId: deletePersonalityPerceptionResult
      summary: Hard-delete one aggregate perception response
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{20,256}$
      responses:
        '204':
          description: Response deleted
        '404':
          description: Capability invalid or expired
      tags:
      - Personality
  /api/v1/personality/manage/{token}:
    get:
      operationId: getPersonalityPerceptionManagement
      summary: Read creator factor sums and aggregate-only response summaries
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{20,256}$
      responses:
        '200':
          description: Creator management summary without item vectors or ranks
        '404':
          description: Capability invalid or expired
      tags:
      - Personality
    delete:
      operationId: deletePersonalityPerceptionChallenge
      summary: Hard-delete the challenge and cascade every aggregate response
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{20,256}$
      responses:
        '204':
          description: Challenge and responses deleted
        '404':
          description: Capability invalid or expired
      tags:
      - Personality
  /api/v1/personality/challenges/{code}/report:
    post:
      operationId: reportPersonalityPerceptionChallenge
      summary: Submit one fixed-reason safety report
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{20,32}$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - reason
              properties:
                reason:
                  type: string
                  enum:
                  - harassment_or_misuse
                  - impersonation
                  - sensitive_content
                  - other_safety
      responses:
        '202':
          description: Report accepted
        '400':
          description: Invalid reason
      tags:
      - Personality
components:
  schemas:
    MiniIpipResponseVector:
      type: array
      minItems: 20
      maxItems: 20
      items:
        $ref: '#/components/schemas/MiniIpipResponseEntry'
    MiniIpipResponseEntry:
      type: object
      additionalProperties: false
      required:
      - itemId
      - response
      properties:
        itemId:
          type: string
          pattern: ^mini-ipip-(?:0[1-9]|1[0-9]|20)$
        response:
          type: integer
          enum:
          - 1
          - 2
          - 3
          - 4
          - 5
externalDocs:
  description: ViewsMeet participation instructions
  url: https://viewsmeet.com/.well-known/agent-skills/viewsmeet-participation/SKILL.md