OpenAPI Specification
openapi: 3.0.3
info:
title: Fathom Analytics REST Account Sites API
description: 'Privacy-first, GDPR-compliant, cookie-free website analytics API. Manage sites, events, and milestones; generate aggregated custom reports; and retrieve real-time visitor counts. Authentication uses Bearer token API keys generated in the account settings area.
'
version: '1'
contact:
name: Fathom Analytics Support
email: support@usefathom.com
termsOfService: https://usefathom.com/terms
license:
name: Proprietary
servers:
- url: https://api.usefathom.com/v1
description: Fathom Analytics API v1
security:
- BearerAuth: []
tags:
- name: Sites
description: Site management
paths:
/sites:
get:
operationId: listSites
summary: List sites
description: Returns a paginated list of sites belonging to the account.
tags:
- Sites
parameters:
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/StartingAfter'
- $ref: '#/components/parameters/EndingBefore'
responses:
'200':
description: Paginated list of sites
content:
application/json:
schema:
$ref: '#/components/schemas/SiteList'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createSite
summary: Create site
description: Creates a new site.
tags:
- Sites
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SiteCreate'
responses:
'200':
description: Created site object
content:
application/json:
schema:
$ref: '#/components/schemas/Site'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/sites/{site_id}:
get:
operationId: getSite
summary: Get site
description: Returns a single site by ID.
tags:
- Sites
parameters:
- $ref: '#/components/parameters/SiteId'
responses:
'200':
description: Site object
content:
application/json:
schema:
$ref: '#/components/schemas/Site'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: updateSite
summary: Update site
description: Updates a site's name or sharing settings.
tags:
- Sites
parameters:
- $ref: '#/components/parameters/SiteId'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/SiteUpdate'
responses:
'200':
description: Updated site object
content:
application/json:
schema:
$ref: '#/components/schemas/Site'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteSite
summary: Delete site
description: Permanently deletes a site and all its data.
tags:
- Sites
parameters:
- $ref: '#/components/parameters/SiteId'
responses:
'200':
description: Empty object on success
content:
application/json:
schema:
type: object
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/sites/{site_id}/data:
delete:
operationId: wipeSiteData
summary: Wipe site data
description: Permanently wipes all analytics data for a site without deleting the site itself.
tags:
- Sites
parameters:
- $ref: '#/components/parameters/SiteId'
responses:
'200':
description: Empty object on success
content:
application/json:
schema:
type: object
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
SiteUpdate:
type: object
properties:
name:
type: string
description: New display name for the site.
sharing:
type: string
enum:
- none
- private
- public
share_password:
type: string
SiteCreate:
type: object
required:
- name
properties:
name:
type: string
description: Display name for the site.
sharing:
type: string
enum:
- none
- private
- public
description: Sharing setting for the site dashboard.
share_password:
type: string
description: Password for private sharing (required when sharing is private).
SiteList:
type: object
properties:
object:
type: string
example: list
data:
type: array
items:
$ref: '#/components/schemas/Site'
has_more:
type: boolean
Error:
type: object
properties:
error:
type: string
description: Human-readable error message.
required:
- error
Site:
type: object
properties:
id:
type: string
description: Unique site identifier.
object:
type: string
example: site
name:
type: string
description: Site display name.
sharing:
type: string
enum:
- none
- private
- public
description: Sharing setting for the site dashboard.
created_at:
type: string
format: date-time
description: ISO 8601 timestamp when the site was created.
responses:
BadRequest:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
parameters:
Limit:
name: limit
in: query
required: false
description: Number of results per page (1-100, default 10).
schema:
type: integer
minimum: 1
maximum: 100
default: 10
StartingAfter:
name: starting_after
in: query
required: false
description: Cursor for forward pagination — return results after this ID.
schema:
type: string
EndingBefore:
name: ending_before
in: query
required: false
description: Cursor for backward pagination — return results before this ID.
schema:
type: string
SiteId:
name: site_id
in: path
required: true
description: Unique identifier for the site.
schema:
type: string
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: API key generated in account settings at https://app.usefathom.com/api