openapi: 3.2.0
info:
  title: Bitculator Data Editorial API
  description: 'Programmatic access to Bitculator market data: coins, prices, history, exchanges, trust scores, tickers, pairs, wallets, sentiment, technical indicators, liquidations, editorial content, and calculators.'
  version: 1.0.0
servers:
- url: https://bitculator.com
security:
- default: []
tags:
- name: Editorial
  description: 'Editorial articles — published (ACTIVE) only. `locale` picks the content language

    with per-field English fallback (the payload reports which `locale` actually won).

    Articles can be filtered by tag or by a related coin/exchange/wallet slug. API

    reads deliberately do NOT increment view counts.'
paths:
  /api/v1/coins/{slug}/videos:
    parameters:
    - in: path
      name: slug
      description: The coin's slug identifier.
      example: bitcoin
      required: true
      schema:
        type: string
    get:
      summary: Coin videos
      operationId: coinVideos
      description: Curated videos attached to a coin (the coin page's Videos tab), paginated.
      parameters:
      - in: query
        name: page
        description: Page number (1-based).
        example: 1
        required: false
        schema:
          type: integer
          description: Page number (1-based).
          example: 1
      - in: query
        name: per_page
        description: Rows per page (1–50, default 10).
        example: 10
        required: false
        schema:
          type: integer
          description: Rows per page (1–50, default 10).
          example: 10
      - in: query
        name: type
        description: Filter by video type (e.g. `overview`, `tutorial`, `explainer`, `review`, `analysis`, `news`).
        example: review
        required: false
        schema:
          type: string
          description: Filter by video type (e.g. `overview`, `tutorial`, `explainer`, `review`, `analysis`, `news`).
          example: review
      - in: query
        name: search
        description: Free-text match on the title.
        example: halving
        required: false
        schema:
          type: string
          description: Free-text match on the title.
          example: halving
      responses: []
      tags:
      - Editorial
  /api/v1/coins/{slug}/insights:
    parameters:
    - in: path
      name: slug
      description: The coin's slug identifier.
      example: bitcoin
      required: true
      schema:
        type: string
    get:
      summary: Coin insight timeline
      operationId: coinInsightTimeline
      description: 'The coin''s insight timeline — the same payload the asset page''s insights panel

        uses, windowed by `offset`/`limit`.'
      parameters:
      - in: query
        name: locale
        description: Content language (falls back to English).
        example: en
        required: false
        schema:
          type:
          - string
          - 'null'
          description: Content language (falls back to English).
          example: en
      - in: query
        name: offset
        description: Rows to skip (0–500, default 0).
        example: 0
        required: false
        schema:
          type:
          - integer
          - 'null'
          description: Rows to skip (0–500, default 0).
          example: 0
      - in: query
        name: limit
        description: Rows to return (1–50, default 5).
        example: 5
        required: false
        schema:
          type:
          - integer
          - 'null'
          description: Rows to return (1–50, default 5).
          example: 5
      responses: []
      tags:
      - Editorial
  /api/v1/articles:
    get:
      summary: List articles
      operationId: listArticles
      description: 'Published articles, newest first, paginated. Filter by `tag` or by a related

        `coin` / `exchange` / `wallet` slug, or free-text `search`. Each row is a summary

        (title, subtitle, tags, reading time, hero image, related entities, dates).'
      parameters:
      - in: query
        name: page
        description: Page number (1-based).
        example: 1
        required: false
        schema:
          type:
          - integer
          - 'null'
          description: Page number (1-based).
          example: 1
      - in: query
        name: per_page
        description: Rows per page (1–50, default 20).
        example: 20
        required: false
        schema:
          type:
          - integer
          - 'null'
          description: Rows per page (1–50, default 20).
          example: 20
      - in: query
        name: locale
        description: Content language (falls back to English).
        example: en
        required: false
        schema:
          type:
          - string
          - 'null'
          description: Content language (falls back to English).
          example: en
      - in: query
        name: tag
        description: 'Filter by tag: news, guide, tutorial, explainer, analysis, review, trading, overview or information.'
        example: guide
        required: false
        schema:
          type:
          - string
          - 'null'
          description: 'Filter by tag: news, guide, tutorial, explainer, analysis, review, trading, overview or information.'
          example: guide
      - in: query
        name: coin
        description: Filter to articles related to this coin slug.
        example: bitcoin
        required: false
        schema:
          type:
          - string
          - 'null'
          description: Filter to articles related to this coin slug.
          example: bitcoin
      - in: query
        name: exchange
        description: Filter to articles related to this exchange slug.
        example: binance-exchange
        required: false
        schema:
          type:
          - string
          - 'null'
          description: Filter to articles related to this exchange slug.
          example: binance-exchange
      - in: query
        name: wallet
        description: Filter to articles related to this wallet slug.
        example: frostsnap
        required: false
        schema:
          type:
          - string
          - 'null'
          description: Filter to articles related to this wallet slug.
          example: frostsnap
      - in: query
        name: search
        description: Free-text match on heading/subheading.
        example: halving
        required: false
        schema:
          type:
          - string
          - 'null'
          description: Free-text match on heading/subheading.
          example: halving
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                  - id: 14
                    slug: what-is-bitcoin
                    title: What Is Bitcoin?
                    subtitle: A plain-language introduction to the first cryptocurrency.
                    locale: en
                    tags:
                    - guide
                    - analysis
                    reading_time_minutes: 7
                    hero_image: https://bitculator.com/storage/media/articles/what-is-bitcoin.png
                    entities: []
                    published_at: '2026-06-21'
                    updated_at: '2026-06-21'
                  meta:
                    current_page: 1
                    per_page: 20
                    total: 10
                    last_page: 1
                properties:
                  data:
                    type: array
                    example:
                    - id: 14
                      slug: what-is-bitcoin
                      title: What Is Bitcoin?
                      subtitle: A plain-language introduction to the first cryptocurrency.
                      locale: en
                      tags:
                      - guide
                      - analysis
                      reading_time_minutes: 7
                      hero_image: https://bitculator.com/storage/media/articles/what-is-bitcoin.png
                      entities: []
                      published_at: '2026-06-21'
                      updated_at: '2026-06-21'
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 14
                        slug:
                          type: string
                          example: what-is-bitcoin
                        title:
                          type: string
                          example: What Is Bitcoin?
                        subtitle:
                          type: string
                          example: A plain-language introduction to the first cryptocurrency.
                        locale:
                          type: string
                          example: en
                        tags:
                          type: array
                          example:
                          - guide
                          - analysis
                          items:
                            type: string
                        reading_time_minutes:
                          type: integer
                          example: 7
                        hero_image:
                          type: string
                          example: https://bitculator.com/storage/media/articles/what-is-bitcoin.png
                        entities:
                          type: array
                          example: []
                        published_at:
                          type: string
                          example: '2026-06-21'
                        updated_at:
                          type: string
                          example: '2026-06-21'
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 20
                      total:
                        type: integer
                        example: 10
                      last_page:
                        type: integer
                        example: 1
      tags:
      - Editorial
  /api/v1/articles/{slug}:
    parameters:
    - in: path
      name: slug
      description: The article's slug.
      example: what-is-bitcoin
      required: true
      schema:
        type: string
    get:
      summary: Get an article
      operationId: getAnArticle
      description: 'One published article with its full body, tags, hero image, helpful counters and

        related entities. `locale` picks the content language with per-field English

        fallback (the payload reports which locale actually won).'
      parameters:
      - in: query
        name: locale
        description: Content language (falls back to English).
        example: en
        required: false
        schema:
          type:
          - string
          - 'null'
          description: Content language (falls back to English).
          example: en
      responses: []
      tags:
      - Editorial
  /api/v1/articles/{slug}/feedback:
    parameters:
    - in: path
      name: slug
      description: The article's slug.
      example: what-is-bitcoin
      required: true
      schema:
        type: string
    post:
      summary: Submit article feedback
      operationId: submitArticleFeedback
      description: 'Registers a thumbs-up/down on an article — the same counters the web''s helpful

        buttons use. Per-key throttling applies upstream.'
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    article: what-is-bitcoin
                    helpful_yes: 13
                    helpful_no: 2
                properties:
                  data:
                    type: object
                    properties:
                      article:
                        type: string
                        example: what-is-bitcoin
                      helpful_yes:
                        type: integer
                        example: 13
                      helpful_no:
                        type: integer
                        example: 2
      tags:
      - Editorial
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                helpful:
                  type: boolean
                  description: '`true` for helpful, `false` for not helpful.'
                  example: true
              required:
              - helpful
  /api/v1/videos/{id}:
    parameters:
    - in: path
      name: id
      description: The video id.
      example: 87
      required: true
      schema:
        type: integer
    get:
      summary: Get a video
      operationId: getAVideo
      description: 'One curated video with its YouTube id, title, type, duration and the

        coins/exchanges/wallets it is attached to.'
      parameters: []
      responses: []
      tags:
      - Editorial
  /api/v1/insights:
    get:
      summary: List insights
      operationId: listInsights
      description: 'AI-generated market insights, paginated. Filter by `type`, a related `coin` slug

        or free-text `search`; `locale` picks the headline/summary language with English

        fallback.'
      parameters:
      - in: query
        name: page
        description: Page number (1-based).
        example: 1
        required: false
        schema:
          type:
          - integer
          - 'null'
          description: Page number (1-based).
          example: 1
      - in: query
        name: per_page
        description: Rows per page (1–50, default 20).
        example: 20
        required: false
        schema:
          type:
          - integer
          - 'null'
          description: Rows per page (1–50, default 20).
          example: 20
      - in: query
        name: locale
        description: Content language (falls back to English).
        example: en
        required: false
        schema:
          type:
          - string
          - 'null'
          description: Content language (falls back to English).
          example: en
      - in: query
        name: type
        description: 'Filter by insight type: `per_asset`, `market_overview` or `narrative`.'
        example: per_asset
        required: false
        schema:
          type:
          - string
          - 'null'
          description: 'Filter by insight type: `per_asset`, `market_overview` or `narrative`.'
          example: per_asset
      - in: query
        name: coin
        description: Filter to insights about this coin slug.
        example: bitcoin
        required: false
        schema:
          type:
          - string
          - 'null'
          description: Filter to insights about this coin slug.
          example: bitcoin
      - in: query
        name: search
        description: Free-text match on the headline.
        example: etf
        required: false
        schema:
          type:
          - string
          - 'null'
          description: Free-text match on the headline.
          example: etf
      - in: query
        name: sort
        description: 'Sort order: `first_reported` (default) or `last_updated`.'
        example: first_reported
        required: false
        schema:
          type:
          - string
          - 'null'
          description: 'Sort order: `first_reported` (default) or `last_updated`.'
          example: first_reported
      responses: []
      tags:
      - Editorial
  /api/v1/insights/{id}:
    parameters:
    - in: path
      name: id
      description: The insight id.
      example: 101
      required: true
      schema:
        type: integer
    get:
      summary: Get an insight
      operationId: getAnInsight
      description: 'One insight with its full payload — headline, summary, source-article timeline

        and related coins.'
      parameters:
      - in: query
        name: locale
        description: Content language (falls back to English).
        example: en
        required: false
        schema:
          type:
          - string
          - 'null'
          description: Content language (falls back to English).
          example: en
      responses: []
      tags:
      - Editorial
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: Create a Data API key in your <a href="/user/developer/api">developer console</a> — keys are Bearer-only and carry the <code>data-api</code> ability. Keep them server-side; they are never meant for client-side embedding.