AgentDeals Freshness API

openapi: 3.2.0
info:
  title: Agentdeals Dev Freshness API
  version: 0.1.0
  contact:
    name: AgentDeals
    url: https://agentdeals.dev
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  description: 'Operations tagged Freshness across 2 of this provider''s published API definitions: agentdeals-dev.json, agentdeals-dev-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://agentdeals.dev
  description: Production server
security: []
tags:
- name: Freshness
paths:
  /api/freshness:
    get:
      summary: Get data freshness metrics
      description: 'Returns data quality metrics. Two counts are reported side by side and they are not interchangeable: confirmed_* counts offers whose published terms the verification store can source to a read that confirmed them, and stamped_* counts offers by the catalogue date beside the entry, which records when it was last written and is not a confirmation. freshness_score is computed from the confirmed count; the catalogue-date share is published separately as stamp_score.'
      parameters: []
      responses:
        '200':
          description: Data freshness metrics
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_offers:
                    type: integer
                  stamped_within_7_days:
                    type: integer
                    description: Offers whose catalogue date (verifiedDate) falls within 7 days. The catalogue date records when the entry was last written and is not a confirmation.
                  stamped_within_30_days:
                    type: integer
                    description: Offers whose catalogue date falls within 30 days.
                  stamped_within_90_days:
                    type: integer
                    description: Offers whose catalogue date falls within 90 days. This count was published as verified_within_90_days until 2026-09-14.
                  stamped_within_180_days:
                    type: integer
                    description: Offers whose catalogue date falls within 180 days.
                  confirmed_within_7_days:
                    type: integer
                    description: Offers whose published terms the verification store can source to a read that confirmed them within 7 days.
                  confirmed_within_30_days:
                    type: integer
                    description: Offers confirmed by a read within 30 days.
                  confirmed_within_90_days:
                    type: integer
                    description: Offers confirmed by a read within 90 days. freshness_score is computed from this.
                  confirmed_within_180_days:
                    type: integer
                    description: Offers confirmed by a read within 180 days.
                  offers_holding_a_confirmation:
                    type: integer
                    description: Offers for which the verification store holds any confirmation at all.
                  oldest_confirmation_held:
                    type:
                    - string
                    - 'null'
                    format: date
                    description: The oldest confirmation still held for any offer. This is not the date the store opened — a confirmation superseded by a later read is no longer held.
                  attempted_within_90_days:
                    type: integer
                    description: Offers the verification store attempted to re-read within 90 days, whether or not the read confirmed anything. Read against confirmed_within_90_days this separates offers we have not reached from offers we reached without confirming.
                  freshness_score:
                    type: integer
                    description: confirmed_within_90_days as a percentage of total_offers — the share of the catalogue whose published terms we can source to a read that confirmed them. This field reported the catalogue-date share until 2026-09-14; that share is now published as stamp_score.
                  stamp_score:
                    type: integer
                    description: stamped_within_90_days as a percentage of total_offers.
                  stalest_entries:
                    type: array
                    items:
                      type: object
                      properties:
                        vendor:
                          type: string
                        category:
                          type: string
                        verifiedDate:
                          type: string
                          format: date
                        last_read_date:
                          type: string
                          format: date
                        confirmed_on:
                          type:
                          - string
                          - 'null'
                          format: date
                          description: The date the store confirmed these terms, or null where it holds none.
                        url:
                          type: string
                          format: uri
                        days_since_verified:
                          type: integer
                        days_since_read:
                          type: integer
                  freshest_entries:
                    type: array
                    items:
                      type: object
                      properties:
                        vendor:
                          type: string
                        category:
                          type: string
                        verifiedDate:
                          type: string
                          format: date
                        last_read_date:
                          type: string
                          format: date
                        confirmed_on:
                          type:
                          - string
                          - 'null'
                          format: date
                          description: The date the store confirmed these terms, or null where it holds none.
                        url:
                          type: string
                          format: uri
                        days_since_verified:
                          type: integer
                        days_since_read:
                          type: integer
                  by_category:
                    type: array
                    items:
                      type: object
                      properties:
                        category:
                          type: string
                        count:
                          type: integer
                        avg_days_since_verified:
                          type: integer
                          description: Mean age in days of the category's catalogue dates. Not a confirmation age.
                        freshness_score:
                          type: integer
                          description: confirmed_within_90_days as a percentage of the category's count.
                        stamp_score:
                          type: integer
                          description: stamped_within_90_days as a percentage of the category's count.
                        confirmed_within_90_days:
                          type: integer
                        stamped_within_90_days:
                          type: integer
                  quarantine:
                    type: object
                    description: Offers the re-verification job has stopped checking daily because three consecutive checks failed. They are retried on a backoff; the entry says what failed and when it is next due.
                    properties:
                      count:
                        type: integer
                      retry_after_days:
                        type: integer
                      by_reason:
                        type: object
                        additionalProperties:
                          type: integer
                      entries:
                        type: array
                        items:
                          type: object
                          properties:
                            vendor:
                              type: string
                            url:
                              type: string
                              format: uri
                            consecutive_failures:
                              type: integer
                            failure_category:
                              type:
                              - string
                              - 'null'
                            last_error:
                              type:
                              - string
                              - 'null'
                            last_attempt_at:
                              type:
                              - string
                              - 'null'
                              format: date
                            last_success:
                              type:
                              - string
                              - 'null'
                              format: date
                            quarantined_since:
                              type:
                              - string
                              - 'null'
                              format: date
                            next_retry:
                              type:
                              - string
                              - 'null'
                              format: date
                  superseded_terms:
                    type: object
                    description: 'Offers whose stored description one of our own in-force change records names as the previous terms. Neither freshness_score nor stamp_score counts them: a read that finds a change records what it found in the change log and leaves the catalogue entry saying the old thing, so the entry is neither confirmed nor restated. The vendor page for such an offer withholds our stored terms and quotes the reading instead.'
                    properties:
                      offers_whose_stored_terms_a_record_supersedes:
                        type: integer
                        description: Offers our own in-force change log contradicts.
                      offers_we_could_restate_from_a_sourced_reading:
                        type: integer
                        description: How many of those records carry a dated reading with a source URL — the sentence the vendor page already shows in place of our terms.
                      oldest_reading_we_are_withholding_behind:
                        type:
                        - string
                        - 'null'
                        format: date
                        description: The oldest such reading. How far back the longest-standing withheld entry goes.
                      offers_we_may_restate_from_their_reading:
                        type: integer
                        description: Withheld offers where the reading answers for the tier the entry describes, so it may be stored as our terms, attributed to the reading and to the date it was read.
                      offers_we_refuse_to_restate:
                        type: object
                        additionalProperties:
                          type: integer
                        description: 'The rest, counted by the ground we refuse on. A reading that prices a different plan than the entry describes is not a restatement of that entry. Nor is one that reports on the page it was read from rather than stating that page''s terms, one that states no figure where the terms it would replace state several, or one that drops the cap on how many people may use the free tier — a restatement may drop a caveat, but not the fact that decides the tier. One ground is not a rule and says so in its name: it counts the readings held back by name, each of which is waiting on a rule that should reach it. One counts entries whose restatement was put back by hand: the record it was taken from may not restate it a second time, though a newer record contradicting the entry still may.'
                      offers_re_read_since_the_record_and_still_withheld:
                        type: integer
                        description: Withheld offers whose cited page we have read again since the reading and which we still cannot answer from our own stored terms.
                      restatements_keeping_the_stored_sentence_saying_what_the_product_is:
                        type: integer
                        description: How many of the restatements we may make open on the stored clause saying what the product is, with only the terms after it replaced. The rest hold no such clause and take the reading whole.
                      offers_whose_terms_came_from_a_reading:
                        type: integer
                        description: Offers whose stored description was taken from a dated reading of the vendor's page rather than written by us or confirmed against that page. This is a fourth state beside confirmed, stamped and read — a read disagreed with us and we took its words — and it is counted here and nowhere else, because neither verifiedDate nor the confirmation date may move on a restatement.
                      offers_restated_by_change_type:
                        type: object
                        additionalProperties:
                          type: integer
                        description: Those offers counted by the verdict of the change record the reading came from.
                      oldest_reading_we_publish_as_our_terms:
                        type:
                        - string
                        - 'null'
                        format: date
                        description: The oldest reading standing as an offer's terms. How far back the longest-standing restatement goes.
                      newest_reading_we_publish_as_our_terms:
                        type:
                        - string
                        - 'null'
                        format: date
                        description: The newest such reading.
      tags:
      - Freshness
      operationId: getApiFreshness
      x-operation-id-source: derived
    servers:
    - url: https://agentdeals.dev
      description: Production server
x-refined-from:
- agentdeals-dev.json
- agentdeals-dev-openapi.json