Dropto Promotions API

openapi: 3.2.0
info:
  title: Drop2Run.Api | v1 Promotions API
  version: 1.0.0
servers:
- description: Production
  url: https://dropto.run
tags:
- name: Promotions
paths:
  /api/promotions:
    get:
      operationId: GetOfferedPromotions
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfferedPromotionsResponse'
          description: OK
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Forbidden
      security:
      - session: []
      - accessToken: []
      summary: Lists the promotions this account can still claim
      tags:
      - Promotions
  /api/promotions/preview:
    post:
      operationId: PreviewPromotion
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreviewPromotionRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfferedPromotion'
          description: OK
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Bad Request
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Forbidden
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Not Found
        '409':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Conflict
      security:
      - session: []
      - accessToken: []
      summary: Shows what a promotion code would give this account, without claiming it
      tags:
      - Promotions
  /api/promotions/redeem:
    post:
      operationId: RedeemPromotion
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedeemPromotionRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedeemPromotionResponse'
          description: OK
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Bad Request
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Forbidden
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Not Found
        '409':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
          description: Conflict
      security:
      - session: []
      - accessToken: []
      summary: Claims a promotion for this account
      tags:
      - Promotions
components:
  schemas:
    OfferedPromotion:
      description: One campaign this account may claim.
      properties:
        allowsFeedback:
          description: Whether claiming it switches on comments.
          type: boolean
        allowsInvitedViewers:
          description: Whether claiming it switches on private sharing by email.
          type: boolean
        allowsPasswordProtection:
          description: Whether claiming it switches on password protection.
          type: boolean
        code:
          description: Its code, or null when there is none to type.
          type:
          - 'null'
          - string
        deltaAccountBytes:
          description: Extra storage it gives, or null when it gives none.
          format: int64
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - 'null'
          - integer
          - string
        deltaMaxCustomDomains:
          description: Extra custom domains it gives.
          format: int32
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
        deltaMaxSites:
          description: Extra sites it gives, or null when it gives none.
          format: int32
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - 'null'
          - integer
          - string
        deltaSitesPerDay:
          description: 'Extra sites a day the account may create, or null. Only ever set on a campaign aimed at named

            accounts, so only an account the operator chose ever reads a figure here.'
          format: int32
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - 'null'
          - integer
          - string
        deltaWriteOpsPerDay:
          description: Extra publishing operations a day, or null.
          format: int64
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - 'null'
          - integer
          - string
        deltaWriteOpsPerMonth:
          description: Extra publishing operations a month, or null.
          format: int64
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - 'null'
          - integer
          - string
        endsAt:
          description: When claiming closes, or null when it does not.
          format: date-time
          type:
          - 'null'
          - string
        grantExpiresAfterDays:
          description: How long what it gives lasts, or null for good.
          format: int32
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - 'null'
          - integer
          - string
        id:
          description: The campaign, which is what a button with no code to type sends back.
          type: string
        name:
          description: What to call it on the banner.
          type: string
        placesLeft:
          description: 'How many accounts may still claim it, or null when any number may. Read a moment ago and acted on a

            moment later, so it is a number to show rather than a number to trust — the redeem endpoint is what

            decides, and it decides in one statement.'
          format: int32
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - 'null'
          - integer
          - string
        suppressesBadge:
          description: Whether claiming it takes the Drop2Run badge off.
          type: boolean
      required:
      - id
      - code
      - name
      - deltaAccountBytes
      - deltaMaxSites
      - deltaWriteOpsPerMonth
      - deltaWriteOpsPerDay
      - deltaSitesPerDay
      - deltaMaxCustomDomains
      - suppressesBadge
      - allowsInvitedViewers
      - allowsFeedback
      - allowsPasswordProtection
      - grantExpiresAfterDays
      - placesLeft
      - endsAt
      type: object
    ProblemDetails:
      properties:
        detail:
          type:
          - 'null'
          - string
        instance:
          type:
          - 'null'
          - string
        status:
          format: int32
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - 'null'
          - integer
          - string
        title:
          type:
          - 'null'
          - string
        type:
          type:
          - 'null'
          - string
      type: object
    RedeemPromotionResponse:
      description: What was claimed.
      properties:
        expiresAt:
          description: When the grant runs out, or null when it does not.
          format: date-time
          type:
          - 'null'
          - string
        name:
          description: Its name, so the page can say what was applied without a second call.
          type: string
        promotionId:
          description: The campaign claimed.
          type: string
      required:
      - promotionId
      - name
      - expiresAt
      type: object
    RedeemPromotionRequest:
      description: Body of `POST /promotions/redeem`. Exactly one of the two says which campaign.
      properties:
        code:
          description: The code, as typed. Folded to upper case here, so the case somebody used does not matter.
          type:
          - 'null'
          - string
        promotionId:
          description: 'The campaign''s id, for an offer that was listed — a button rather than something to type. Refused for a

            campaign whose audience is `Code`: there the code is the only way in.'
          type:
          - 'null'
          - string
      required:
      - code
      - promotionId
      type: object
    PreviewPromotionRequest:
      description: Body of `POST /promotions/preview`.
      properties:
        code:
          description: 'The code, as typed. Folded to upper case here, so the case somebody used does not matter. Bounded by

            the same length an operator may give one.'
          maxLength: 64
          type: string
      required:
      - code
      type: object
    OfferedPromotionsResponse:
      description: Response of `GET /promotions`.
      properties:
        promotions:
          description: What this account can claim, the ones closing soonest first and the open-ended ones last.
          items:
            $ref: '#/components/schemas/OfferedPromotion'
          type: array
      required:
      - promotions
      type: object
  securitySchemes:
    accessToken:
      description: 'A personal access token, created at /account/tokens. Sent as `Authorization: Bearer d2r_...`. A rejected token answers 401 with `invalid_token`, which is deliberately distinct from the 403 a valid credential gets for something it may not do.'
      scheme: bearer
      type: http
    claimToken:
      description: Returned once when an anonymous site is created, and the only credential that site has until somebody signs in and claims it.
      in: header
      name: X-Claim-Token
      type: apiKey
    session:
      description: The browser session, set by signing in with Google. HttpOnly, so a script cannot read it and a client outside a browser cannot send it.
      in: cookie
      name: d2r_session
      type: apiKey