Crevio Analytics API

openapi: 3.2.0
info:
  title: Crevio API V1 Analytics API
  version: 1.0.0
  description: 'API for the Crevio creator platform — a multi-tenant SaaS for digital product sales.

    Uses snake_case keys following Stripe conventions. All resource IDs are string IDs (e.g., "prod_abc123").


    Authentication is a bearer token: `Authorization: Bearer $CREVIO_API_KEY`.

    List endpoints are cursor-paginated with `limit` and `starting_after`.

    Writes accept an `Idempotency-Key` header and are safe to retry.


    Every response carries IETF RateLimit headers (`RateLimit`, `RateLimit-Policy`) so a client can

    self-throttle, and `Retry-After` on a 429. The quota is 600 requests per minute per credential.


    The API is versioned in the URL path (`/v1`). Nothing is removed without in-band warning: a

    deprecated operation is marked `"deprecated": true` here and serves `Deprecation` (RFC 9745),

    `Sunset` (RFC 8594) and `Link; rel="deprecation"` headers for at least six months before it

    stops answering. See https://crevio.co/docs/developer/guides/versioning.'
  contact:
    email: support@crevio.co
    name: Crevio Support
    url: https://crevio.co/docs
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://crevio.co/legal/terms-of-service
servers:
- url: https://api.crevio.co/v1
  description: Production
security:
- ApiKey: []
tags:
- name: Analytics
  description: Account-wide business analytics
paths:
  /analytics:
    get:
      summary: Get business overview
      description: 'Account-wide business pulse in one call: revenue, orders, leads, new customers, and live-site traffic over a date range, each compared against the immediately preceding period of equal length. Defaults to the last 7 days; the range cannot exceed 366 days. Use this as the starting point for any business review — drill into a specific site with GET /sites/{id}/analytics, and into records with the orders/customers list endpoints.'
      operationId: getBusinessOverview
      x-crevio-sdk-method: overview
      tags:
      - Analytics
      security:
      - ApiKey: []
      parameters:
      - name: start_date
        in: query
        description: Start of the date range (inclusive), as an ISO-8601 date (YYYY-MM-DD). Defaults to 7 days before end_date.
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        description: End of the date range (inclusive), as an ISO-8601 date (YYYY-MM-DD). Defaults to today.
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Business overview for the requested period
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - business_overview
                  period:
                    type: object
                    description: The resolved date range the metrics cover.
                    properties:
                      start_date:
                        type: string
                        format: date
                      end_date:
                        type: string
                        format: date
                      days:
                        type: integer
                    required:
                    - start_date
                    - end_date
                    - days
                  previous_period:
                    type: object
                    description: 'The comparison period: the range of equal length immediately before period.start_date.'
                    properties:
                      start_date:
                        type: string
                        format: date
                      end_date:
                        type: string
                        format: date
                    required:
                    - start_date
                    - end_date
                  currency:
                    type: string
                    description: Lowercase ISO currency code all monetary amounts are expressed in (the account's display currency).
                  lifetime_revenue:
                    type: integer
                    description: All-time revenue in the account currency, in the smallest currency unit (cents for USD).
                  revenue:
                    type: object
                    description: Revenue in the account currency, in the smallest currency unit (cents for USD), with the preceding period of equal length for comparison and a per-day time series.
                    properties:
                      total:
                        type: integer
                      previous_total:
                        type: integer
                      change_pct:
                        type:
                        - number
                        - 'null'
                        description: Percent change vs. the previous period; null when the previous period was zero (no baseline).
                      by_day:
                        type: array
                        items:
                          type: object
                          properties:
                            date:
                              type: string
                              format: date
                            amount:
                              type: integer
                              description: Revenue for the day in the account currency, in the smallest currency unit.
                          required:
                          - date
                          - amount
                        description: Per-day series with one entry per day in the period; days with no activity are zero-filled.
                    required:
                    - total
                    - previous_total
                  orders:
                    type: object
                    description: Period totals with the preceding period of equal length for comparison and a per-day time series.
                    properties:
                      total:
                        type: number
                      previous_total:
                        type: number
                      change_pct:
                        type:
                        - number
                        - 'null'
                        description: Percent change vs. the previous period; null when the previous period was zero (no baseline).
                      by_day:
                        type: array
                        items:
                          type: object
                          properties:
                            date:
                              type: string
                              format: date
                            count:
                              type: number
                              description: Orders created that day (excluding pending and failed).
                          required:
                          - date
                          - count
                        description: Per-day series with one entry per day in the period; days with no activity are zero-filled.
                    required:
                    - total
                    - previous_total
                  leads:
                    type: object
                    description: Period totals with the preceding period of equal length for comparison and a per-day time series.
                    properties:
                      total:
                        type: number
                      previous_total:
                        type: number
                      change_pct:
                        type:
                        - number
                        - 'null'
                        description: Percent change vs. the previous period; null when the previous period was zero (no baseline).
                      by_day:
                        type: array
                        items:
                          type: object
                          properties:
                            date:
                              type: string
                              format: date
                            count:
                              type: number
                              description: Leads captured that day.
                          required:
                          - date
                          - count
                        description: Per-day series with one entry per day in the period; days with no activity are zero-filled.
                    required:
                    - total
                    - previous_total
                  new_customers:
                    type: object
                    description: Period totals with the preceding period of equal length for comparison.
                    properties:
                      total:
                        type: number
                      previous_total:
                        type: number
                      change_pct:
                        type:
                        - number
                        - 'null'
                        description: Percent change vs. the previous period; null when the previous period was zero (no baseline).
                    required:
                    - total
                    - previous_total
                  refunds:
                    type: object
                    description: Orders created in the period that have since been refunded or partially refunded. Attribution is by order date (refund timestamps are not tracked); amounts are in the account currency, in the smallest currency unit.
                    properties:
                      count:
                        type: integer
                      previous_count:
                        type: integer
                      amount:
                        type: integer
                      previous_amount:
                        type: integer
                    required:
                    - count
                    - previous_count
                    - amount
                    - previous_amount
                  top_products:
                    type: array
                    description: Top products by units sold over the period (units, not revenue — per-item revenue attribution is not tracked). Empty when nothing sold.
                    items:
                      type: object
                      properties:
                        id:
                          type:
                          - string
                          - 'null'
                          description: Prefix id of the product (e.g. prod_abc123).
                        name:
                          type: string
                        units:
                          type: integer
                        orders:
                          type: integer
                          description: Distinct orders containing the product.
                      required:
                      - name
                      - units
                      - orders
                  traffic:
                    type:
                    - object
                    - 'null'
                    description: Traffic for the account's live site; null when no site is deployed. Zeros may also mean analytics collection is temporarily degraded.
                    properties:
                      site_id:
                        type: string
                        description: Prefix id of the live site (e.g. site_abc123).
                      visitors:
                        type: object
                        description: Period totals with the preceding period of equal length for comparison and a per-day time series.
                        properties:
                          total:
                            type: number
                          previous_total:
                            type: number
                          change_pct:
                            type:
                            - number
                            - 'null'
                            description: Percent change vs. the previous period; null when the previous period was zero (no baseline).
                          by_day:
                            type: array
                            items:
                              type: object
                              properties:
                                date:
                                  type: string
                                  format: date
                                count:
                                  type: number
                                  description: Unique visitors that day.
                              required:
                              - date
                              - count
                            description: Per-day series with one entry per day in the period; days with no activity are zero-filled.
                        required:
                        - total
                        - previous_total
                      pageviews:
                        type: object
                        description: Period totals with the preceding period of equal length for comparison.
                        properties:
                          total:
                            type: number
                          previous_total:
                            type: number
                          change_pct:
                            type:
                            - number
                            - 'null'
                            description: Percent change vs. the previous period; null when the previous period was zero (no baseline).
                        required:
                        - total
                        - previous_total
                      top_sources:
                        type: array
                        description: Top traffic sources by unique visitors over the period.
                        items:
                          type: object
                          properties:
                            source:
                              type: string
                            count:
                              type: integer
                          required:
                          - source
                          - count
                      top_pages:
                        type: array
                        description: Top pages by unique visitors over the period.
                        items:
                          type: object
                          properties:
                            path:
                              type: string
                            count:
                              type: integer
                          required:
                          - path
                          - count
                required:
                - object
                - period
                - previous_period
                - currency
                - lifetime_revenue
                - revenue
                - orders
                - leads
                - new_customers
                - refunds
                - top_products
                - traffic
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-crevio-approval: allow
      x-codeSamples:
      - lang: typescript
        label: Typescript (SDK)
        source: "import { Crevio } from \"@crevio/sdk\";\n\nconst crevio = new Crevio({\n  apiKey: process.env[\"CREVIO_API_KEY\"] ?? \"\",\n});\n\nasync function run() {\n  const result = await crevio.analytics.overview();\n\n  console.log(result);\n}\n\nrun();"
components:
  responses:
    TooManyRequests:
      description: 'Rate limit exceeded — 600 requests per minute per owner on the free tier: every API key and OAuth token one person holds on an account shares one budget, and the account''s team keys share another. Retry after the number of seconds in `Retry-After`.'
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: rate_limit_exceeded
              message: Too many requests. Please retry later.
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: bad_request
              message: The request was malformed or contained invalid parameters
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: authentication_required
              message: You did not provide an API key.
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
              - api_error
              - invalid_request_error
              - validation_error
            code:
              type: string
            message:
              type: string
            param:
              type: string
            errors:
              type: object
            doc_url:
              type: string
          required:
          - type
          - message
      required:
      - error
  headers:
    Sunset:
      description: Present only on a deprecated operation. HTTP-date (RFC 8594) after which the operation stops responding. Always at least six months after `Deprecation`.
      schema:
        type: string
        examples:
        - Thu, 01 Oct 2026 00:00:00 GMT
    RateLimit:
      description: 'Remaining quota for the current window, as an IETF structured field: `"default";r=<remaining>;t=<seconds until reset>`.'
      schema:
        type: string
        examples:
        - '"default";r=596;t=11'
    DeprecationLink:
      description: Present only on a deprecated operation. `<url>; rel="deprecation"` pointing at the migration notes.
      schema:
        type: string
        examples:
        - <https://crevio.co/docs/developer/guides/versioning>; rel="deprecation"
    RequestId:
      description: Unique id for this request. Quote it when reporting a problem.
      schema:
        type: string
        examples:
        - 8fe045fe-cb8a-4407-a44d-5df60385e522
    RateLimitPolicy:
      description: 'The quota this credential is subject to: `"default";q=<requests>;w=<window seconds>`.'
      schema:
        type: string
        examples:
        - '"default";q=600;w=60'
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        examples:
        - 11
    Deprecation:
      description: Present only on a deprecated operation. Structured-field date (RFC 9745) — `@` followed by the Unix timestamp at which the operation became deprecated.
      schema:
        type: string
        examples:
        - '@1775001600'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key in the format: Bearer {api_token}'
externalDocs:
  description: Crevio developer documentation
  url: https://crevio.co/docs/developer
x-mint:
  mcp:
    enabled: true
x-api-lifecycle:
  current_major_version: v1
  versioning_scheme: URL path
  deprecation_policy_url: https://crevio.co/docs/developer/guides/versioning
  minimum_notice_days: 183
  deprecation_headers:
  - Deprecation
  - Sunset
  - Link