openapi: 3.1.0
# Published on the public docs site, as a reference page and as this file.
# A contract without this key is internal.
x-docs-visibility: public
info:
  title: Assessor.io API v2 (public) - Campaigns
  version: 1.0.1
  description: |
    Read a machine client's campaigns. This is the external-integrator surface:
    responses are the whitelisted PublicCampaign projection, so the campaign
    access passcode, shareWithAllAccountUsers, branding, and the raw settings
    object are never returned. Requires a service token holding campaigns:read
    and scoped to the accountId in the path.
servers:
  - url: /
security:
  - serviceToken: []
tags:
  - name: PublicCampaigns
paths:
  /api/v2/public/accounts/{accountId}/campaigns:
    get:
      tags: [PublicCampaigns]
      operationId: v2ListCampaigns
      summary: List the account's campaigns.
      description: |
        Paginated list of every campaign in the account, newest-first as the
        persistence layer returns them. Scope campaigns:read.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
        - name: status
          in: query
          required: false
          description: Filter by lifecycle status. Any other value is rejected with 400.
          schema:
            $ref: '#/components/schemas/CampaignStatus'
        - $ref: '../components/v2-common.yaml#/components/parameters/Page'
        - $ref: '../components/v2-common.yaml#/components/parameters/Limit'
      responses:
        '200':
          description: Campaigns loaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicCampaignListResponse'
        '400': { $ref: '../../v1/components/errors.yaml#/components/responses/BadRequest' }
        '401': { $ref: '../../v1/components/errors.yaml#/components/responses/Unauthorized' }
        '403': { $ref: '../../v1/components/errors.yaml#/components/responses/Forbidden' }
        '429': { $ref: '../../v1/components/errors.yaml#/components/responses/TooManyRequests' }
        '500': { $ref: '../../v1/components/errors.yaml#/components/responses/InternalError' }
  /api/v2/public/accounts/{accountId}/campaigns/{campaignId}:
    get:
      tags: [PublicCampaigns]
      operationId: v2GetCampaign
      summary: Read a single campaign.
      description: |
        Returns 404 when the campaign does not exist OR is owned by a different
        account, so an integrator cannot probe for campaign ids outside its own
        account. Scope campaigns:read.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
        - $ref: '../components/v2-common.yaml#/components/parameters/CampaignId'
      responses:
        '200':
          description: Campaign loaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicCampaignDetailResponse'
        '400': { $ref: '../../v1/components/errors.yaml#/components/responses/BadRequest' }
        '401': { $ref: '../../v1/components/errors.yaml#/components/responses/Unauthorized' }
        '403': { $ref: '../../v1/components/errors.yaml#/components/responses/Forbidden' }
        '404': { $ref: '../../v1/components/errors.yaml#/components/responses/NotFound' }
        '429': { $ref: '../../v1/components/errors.yaml#/components/responses/TooManyRequests' }
        '500': { $ref: '../../v1/components/errors.yaml#/components/responses/InternalError' }
components:
  securitySchemes:
    serviceToken:
      $ref: '../components/v2-security.yaml#/components/securitySchemes/serviceToken'
  schemas:
    CampaignStatus:
      type: string
      enum: [Draft, Active, Inactive]
    CampaignAccess:
      type: object
      description: |
        The three access booleans an integrator is allowed to see. The passcode
        VALUE and the shareWithAllAccountUsers flag are deliberately excluded.
      required: [isPrivate, enableRegistration, enablePasscode]
      properties:
        isPrivate:
          type: boolean
        enableRegistration:
          type: boolean
        enablePasscode:
          type: boolean
          description: Whether a passcode is required. The passcode itself is never returned.
    CampaignLifecycle:
      type: object
      required: [cycle]
      properties:
        cycle:
          type: integer
        opensAt:
          type: integer
          description: Epoch milliseconds.
        closesAt:
          type: integer
          description: Epoch milliseconds.
    PublicCampaign:
      type: object
      description: |
        Whitelisted campaign projection (toPublicCampaign). Optional properties
        are OMITTED, not null, when the underlying value is absent.
      required: [id, name, status, access, lifecycles]
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        status:
          $ref: '#/components/schemas/CampaignStatus'
        order:
          type: integer
        access:
          $ref: '#/components/schemas/CampaignAccess'
        maxParticipants:
          type: integer
        lifecycles:
          type: array
          items:
            $ref: '#/components/schemas/CampaignLifecycle'
        vanityUrl:
          type: string
        participantCount:
          type: integer
        createdAt:
          type: integer
          description: Epoch milliseconds.
    PublicCampaignListResponse:
      allOf:
        - $ref: '../../v1/components/envelopes.yaml#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data, meta]
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/PublicCampaign'
            meta:
              $ref: '../components/v2-common.yaml#/components/schemas/PageMeta'
    PublicCampaignDetailResponse:
      allOf:
        - $ref: '../../v1/components/envelopes.yaml#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data]
          properties:
            data:
              $ref: '#/components/schemas/PublicCampaign'
