Mantic Stamps API

openapi: 3.2.0
info:
  title: Fast Stamps API
  version: 0.1.0
tags:
- name: stamps
paths:
  /webapp/question/{question_id}/stamps:
    post:
      tags:
      - stamps
      summary: Create Stamp
      description: 'Stamp a version of a question into a public snapshot.


        Defaults to the newest visible forecast; ``execution_id`` stamps the one the author is

        looking at instead, so the frozen page matches what they saw.'
      operationId: create_stamp_webapp_question__question_id__stamps_post
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: question_id
        in: path
        required: true
        schema:
          type: integer
          title: Question Id
      - name: execution_id
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Stamp this forecast execution, with the scenarios computed against it. Omit for the newest.
          title: Execution Id
        description: Stamp this forecast execution, with the scenarios computed against it. Omit for the newest.
      - name: campaign_id
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 1
          - type: 'null'
          title: Campaign Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateStampResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /webapp/stamps:
    get:
      tags:
      - stamps
      summary: List Stamps
      description: List the current user's active stamps and their monthly quota.
      operationId: list_stamps_webapp_stamps_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListStampsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - OAuth2AuthorizationCodeBearer: []
  /webapp/stamps/{stamp_id}:
    delete:
      tags:
      - stamps
      summary: Delete Stamp
      description: Soft-delete one of the current user's stamps (does not refund quota).
      operationId: delete_stamp_webapp_stamps__stamp_id__delete
      security:
      - OAuth2AuthorizationCodeBearer: []
      parameters:
      - name: stamp_id
        in: path
        required: true
        schema:
          type: integer
          title: Stamp Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /webapp/public/stamps/{token}:
    get:
      tags:
      - stamps
      summary: Get Public Stamp
      description: 'Fetch a stamped snapshot by token. Unauthenticated by design.


        Human views are counted in Mixpanel (``stamp.viewed``) — no client-side

        telemetry runs on the public page. The webapp renders it server-side, so the

        visitor''s user agent arrives as ``x-client-user-agent`` (this request''s own

        headers describe the Next.js server); a call without it is treated as

        automated and not counted. Nothing identifies the visitor, so this is a view

        tally only. The header is caller-controlled on an unauthenticated route, so

        treat the tally as inflatable — indicative, not audited.'
      operationId: get_public_stamp_webapp_public_stamps__token__get
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicStampResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    StampQuota:
      properties:
        max_per_month:
          type: integer
          title: Max Per Month
        used_this_month:
          type: integer
          title: Used This Month
        remaining_this_month:
          type: integer
          title: Remaining This Month
        unlimited:
          type: boolean
          title: Unlimited
          default: false
      type: object
      required:
      - max_per_month
      - used_this_month
      - remaining_this_month
      title: StampQuota
    PublicStampResponse:
      properties:
        token:
          type: string
          title: Token
        question_id:
          type: integer
          title: Question Id
        title:
          type: string
          title: Title
        created_at:
          type: string
          format: date-time
          title: Created At
        snapshot:
          additionalProperties: true
          type: object
          title: Snapshot
      type: object
      required:
      - token
      - question_id
      - title
      - created_at
      - snapshot
      title: PublicStampResponse
    CreateStampResponse:
      properties:
        stamp:
          $ref: '#/components/schemas/StampResponse'
        quota:
          $ref: '#/components/schemas/StampQuota'
        scenarios_omitted:
          type: integer
          title: Scenarios Omitted
          default: 0
      type: object
      required:
      - stamp
      - quota
      title: CreateStampResponse
    StampResponse:
      properties:
        utm_parameters:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Utm Parameters
        id:
          type: integer
          title: Id
        token:
          type: string
          title: Token
        question_id:
          type: integer
          title: Question Id
        title:
          type: string
          title: Title
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - token
      - question_id
      - title
      - created_at
      title: StampResponse
    ListStampsResponse:
      properties:
        stamps:
          items:
            $ref: '#/components/schemas/StampResponse'
          type: array
          title: Stamps
        quota:
          $ref: '#/components/schemas/StampQuota'
      type: object
      required:
      - stamps
      - quota
      title: ListStampsResponse
  securitySchemes:
    OAuth2AuthorizationCodeBearer:
      type: oauth2
      flows:
        authorizationCode:
          scopes: {}
          authorizationUrl: https://app.mantic.com/auth/oauth2/authorize
          tokenUrl: https://app.mantic.com/auth/oauth2/token