openapi: 3.1.0
info:
  title: Fulcrum Audio Photos API
  description: The Fulcrum API is a RESTful HTTP API for the Fulcrum field data collection platform. It provides programmatic access to forms, records, media (photos, videos, audio, signatures), choice lists, classification sets, projects, layers, memberships, roles, webhooks, ad hoc query and SQL execution, and changesets. Requests and responses use JSON and authenticate with an X-ApiToken header issued from a Fulcrum account.
  version: 0.0.1
  contact:
    name: Fulcrum
    url: https://www.fulcrumapp.com/
servers:
- url: https://api.fulcrumapp.com/api/v2
  description: Fulcrum production API (v2)
security:
- ApiToken: []
tags:
- name: Photos
  description: Photo media attached to records
paths:
  /photos.json:
    get:
      tags:
      - Photos
      summary: List photos
      operationId: listPhotos
      parameters:
      - name: form_id
        in: query
        schema:
          type: string
      - name: record_id
        in: query
        schema:
          type: string
      - name: per_page
        in: query
        schema:
          type: integer
      - name: page
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Photos
          content:
            application/json:
              schema:
                type: object
                properties:
                  photos:
                    type: array
                    items:
                      $ref: '#/components/schemas/Photo'
    post:
      tags:
      - Photos
      summary: Upload photo
      description: Uploads a photo file. Must be uploaded before the parent record references it.
      operationId: uploadPhoto
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                access_key:
                  type: string
                  description: UUID generated by the client used as the photo identifier
                file:
                  type: string
                  format: binary
              required:
              - access_key
              - file
      responses:
        '200':
          description: Photo created
          content:
            application/json:
              schema:
                type: object
                properties:
                  photo:
                    $ref: '#/components/schemas/Photo'
  /photos/{id}.json:
    parameters:
    - $ref: '#/components/parameters/IdPath'
    get:
      tags:
      - Photos
      summary: Get photo metadata
      operationId: getPhoto
      responses:
        '200':
          description: Photo metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  photo:
                    $ref: '#/components/schemas/Photo'
  /photos/{id}.jpg:
    parameters:
    - $ref: '#/components/parameters/IdPath'
    get:
      tags:
      - Photos
      summary: Download photo
      operationId: downloadPhoto
      responses:
        '200':
          description: Photo binary
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
components:
  parameters:
    IdPath:
      name: id
      in: path
      required: true
      description: Resource identifier (UUID)
      schema:
        type: string
        format: uuid
  schemas:
    Photo:
      type: object
      properties:
        access_key:
          type: string
        record_id:
          type: string
          format: uuid
        form_id:
          type: string
          format: uuid
        latitude:
          type: number
        longitude:
          type: number
        file_size:
          type: integer
        content_type:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  securitySchemes:
    ApiToken:
      type: apiKey
      in: header
      name: X-ApiToken
      description: Fulcrum API token issued from a Fulcrum account