openapi: 3.2.0
info:
  title: GoatCounter Export API
  description: <p>Reference documentation for the <a href="https://www.goatcounter.com">GoatCounter</a> API.</p> <p>See <a href="/help/api">/help/api</a> for a more general introduction and a few examples.</p> <p>Viewing this documentation at https://[my-code].goatcounter.com/api2.html (rather than using the www.goatcounter.com) enables the "try" feature.</p>
  version: '0.1'
  contact:
    name: Martin Tournoij
    url: https://www.goatcounter.com/help/api
    email: support@goatcounter.com
security:
- basicAuth: []
tags:
- name: export
paths:
  /api/v0/export:
    post:
      description: 'This starts a new export in the background; this can only be done once an

        hour.'
      operationId: POST_api_v0_export
      responses:
        '202':
          description: 202 Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v2.Export'
        '400':
          description: 400 Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.apiError'
        '401':
          description: 401 Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.authError'
        '403':
          description: 403 Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.authError'
      summary: Start a new export in the background.
      tags:
      - export
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.apiExportRequest'
        required: true
  /api/v0/export/{id}:
    get:
      operationId: GET_api_v0_export_{id}
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: 200 OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v2.Export'
        '400':
          description: 400 Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.apiError'
        '401':
          description: 401 Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.authError'
        '403':
          description: 403 Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.authError'
      summary: Get details about an export.
      tags:
      - export
  /api/v0/export/{id}/download:
    get:
      description: 'The export may take a while to generate, depending on the size. It will

        return a 202 Accepted status code if the export ID is still running.


        Export files are kept for 24 hours, after which they''re deleted. This will

        return a 400 Gone status code if the export has been deleted.'
      operationId: GET_api_v0_export_{id}_download
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: 200 OK (text/csv data)
        '202':
          description: 202 Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.apiError'
            text/csv:
              schema:
                $ref: '#/components/schemas/handlers.apiError'
        '400':
          description: 400 Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.apiError'
            text/csv:
              schema:
                $ref: '#/components/schemas/handlers.apiError'
        '401':
          description: 401 Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.authError'
            text/csv:
              schema:
                $ref: '#/components/schemas/handlers.authError'
        '403':
          description: 403 Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.authError'
            text/csv:
              schema:
                $ref: '#/components/schemas/handlers.authError'
      summary: Download an export file.
      tags:
      - export
components:
  schemas:
    handlers.apiError:
      title: apiError
      description: 'Generic API error. An error will have either the "error" or "errors"

        field set, but not both.'
      type: object
      properties:
        error:
          type: string
        errors:
          type: object
    v2.Export:
      title: Export
      type: object
      properties:
        created_at:
          type: string
          format: date-time
          readOnly: true
        error:
          description: Any errors that may have occured.
          type: string
          readOnly: true
        finished_at:
          type: string
          format: date-time
          readOnly: true
        format:
          description: Export format, csv or json.
          type: string
          readOnly: true
        hash:
          description: SHA256 hash.
          type: string
          readOnly: true
        id:
          type: integer
          readOnly: true
        last_hit_id:
          description: Last hit ID that was exported; can be used as start_from_hit_id.
          type: integer
          readOnly: true
        num_rows:
          type: integer
          readOnly: true
        site_id:
          type: integer
          readOnly: true
        size:
          description: File size in MB.
          type: string
          readOnly: true
        start_from_day:
          description: The day this export was started from, for JSON exports.
          type: string
          format: date-time
        start_from_hit_id:
          description: The hit ID this export was started from, for CSV exports.
          type: integer
    handlers.apiExportRequest:
      title: apiExportRequest
      type: object
      properties:
        format:
          description: Export format, defaults to csv.
          type: string
          enum:
          - 'enum:'
          - csv
          - json
        start_from_day:
          description: The day to start this export from, for JSON exports.
          type: string
          format: date-time
        start_from_hit_id:
          description: Pagination cursor for CSV; only export hits with an ID greater than this.
          type: integer
    handlers.authError:
      title: authError
      description: 'Authentication error: the API key was not provided or incorrect.'
      type: object
      properties:
        Error:
          type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic