openapi: 3.1.0
info:
  title: Gameflip API (GFAPI) Account Listing API
  version: v1
  description: JSON REST API for the Gameflip marketplace, transcribed faithfully from the published GFAPI documentation (https://gameflip.github.io/gfapi/) and the official Node.js client (https://github.com/gameflip/gfapi). Covers listing management and search, exchanges, account profile and wallet history, and Steam item escrow / bulk trade-offer listings. This spec captures the documented endpoints, methods, auth scheme, query parameters, and the common response envelope; request/response object bodies are represented as the generic GfResponse envelope because Gameflip does not publish per-object JSON Schemas.
  x-apievangelist-note: Generated by the API Evangelist enrichment pipeline by transcribing the provider's published REST documentation. Not an official Gameflip OpenAPI.
  contact:
    name: Gameflip Support
    url: https://support.gameflip.com/hc/en-us
servers:
- url: https://production-gameflip.fingershock.com/api/v1
  description: Production
- url: https://test-gameflip.fingershock.com/api/v1
  description: Test / sandbox
security:
- gfapiAuth: []
tags:
- name: Listing
  description: Create and manipulate listings of items for sale.
paths:
  /listing:
    get:
      operationId: searchListings
      tags:
      - Listing
      summary: Search for listings
      description: Search for listings. Response is paginated and ordered. Default filter selects listings with status onsale or sold and not expired. Filter type `term` selects any listing whose property equals any provided value; `tags` additionally supports logical AND via the `^` operator.
      parameters:
      - name: term
        in: query
        schema:
          type: string
        description: Fuzzy search over name and description; generates relevance score.
      - name: category
        in: query
        schema:
          type: string
      - name: platform
        in: query
        schema:
          type: string
      - name: genre
        in: query
        schema:
          type: string
      - name: upc
        in: query
        schema:
          type: string
      - name: shipping_paid_by
        in: query
        schema:
          type: string
          enum:
          - buyer
          - seller
      - name: digital
        in: query
        schema:
          type: boolean
      - name: status
        in: query
        schema:
          type: string
      - name: owner
        in: query
        schema:
          type: string
      - name: condition
        in: query
        schema:
          type: string
      - name: price
        in: query
        schema:
          type: string
        description: Range filter on integer price (cents).
      - name: created
        in: query
        schema:
          type: string
        description: Date range filter.
      - name: updated
        in: query
        schema:
          type: string
        description: Date range filter.
      - name: expiration
        in: query
        schema:
          type: string
        description: Date range filter.
      - name: tags
        in: query
        schema:
          type: string
        description: Term filter supporting OR (comma) and AND (^).
      - name: sort
        in: query
        schema:
          type: string
        description: Array of fieldname:direction (asc|desc). Default _score:desc,created:desc.
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
          maximum: 100
      responses:
        '200':
          description: Paginated list of listings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GfListResponse'
        4XX:
          $ref: '#/components/responses/Error'
    post:
      operationId: createListing
      tags:
      - Listing
      summary: Create a listing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Created listing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GfResponse'
        4XX:
          $ref: '#/components/responses/Error'
  /listing/{id}:
    get:
      operationId: getListing
      tags:
      - Listing
      summary: Get a listing by id
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Listing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GfResponse'
        4XX:
          $ref: '#/components/responses/Error'
    patch:
      operationId: updateListing
      tags:
      - Listing
      summary: Update a listing (JSON Patch)
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: Updated listing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GfResponse'
        4XX:
          $ref: '#/components/responses/Error'
    delete:
      operationId: deleteListing
      tags:
      - Listing
      summary: Delete a listing
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GfResponse'
        4XX:
          $ref: '#/components/responses/Error'
  /listing/{id}/photo:
    post:
      operationId: uploadListingPhoto
      tags:
      - Listing
      summary: Upload a photo for a listing
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          image/jpeg:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Uploaded photo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GfResponse'
        4XX:
          $ref: '#/components/responses/Error'
components:
  responses:
    Error:
      description: Failure response using the common GFAPI envelope
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GfError'
  schemas:
    GfListResponse:
      type: object
      description: Common GFAPI success envelope carrying a list plus a cursor.
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - SUCCESS
          - FAILURE
        data:
          type: array
          items:
            type: object
        next_page:
          type: string
          nullable: true
          description: Cursor URL for the next page, or null when exhausted.
    GfResponse:
      type: object
      description: Common GFAPI success envelope carrying a single object.
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - SUCCESS
          - FAILURE
        data:
          type: object
          nullable: true
    GfError:
      type: object
      description: Common GFAPI failure envelope.
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - FAILURE
        data:
          nullable: true
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: integer
  securitySchemes:
    gfapiAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Gameflip API key plus a rotating TOTP one-time password, sent as `Authorization: GFAPI <apikey>:<totp>`. The TOTP is generated from the account''s TOTP secret (SHA1, 6 digits, 30s period). API keys and TOTP secrets are issued through Gameflip account settings / support during Beta.'