AgentDeals Digest API

openapi: 3.2.0
info:
  title: Agentdeals Dev Digest API
  version: 0.1.0
  contact:
    name: AgentDeals
    url: https://agentdeals.dev
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  description: 'Operations tagged Digest 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: Digest
paths:
  /api/digest:
    get:
      summary: Get weekly pricing digest
      description: Curated weekly summary of developer tool pricing changes, new offers, and upcoming deadlines. Falls back to 30-day window if fewer than 3 changes in the past week.
      parameters: []
      responses:
        '200':
          description: Weekly digest
          content:
            application/json:
              schema:
                type: object
                properties:
                  week:
                    type: string
                    description: Week date range
                  date_range:
                    type: string
                    description: ISO date range
                  deal_changes:
                    type: array
                    items:
                      type: object
                      properties:
                        vendor:
                          type: string
                        change_type:
                          type: string
                        date:
                          type: string
                          format: date
                          description: The day the change took effect if date_meaning is "effective". If date_meaning is "discovered", the day we recorded the change; its effective date is unknown. If date_meaning is "effective_by", the latest day the change can have taken effect. Where archived copies of the vendor's page bracket a change, it is dated by the first copy that shows the new terms.
                        date_source:
                          type: string
                          enum:
                          - vendor_page
                          - hand_written
                          - discovered
                          description: 'Where date came from. "vendor_page": the vendor''s page stated it. "hand_written": a person recorded it before this field existed. "discovered": the page stated no effective date, so date is the day we read the page — do not present it as the date the vendor changed anything.'
                        summary:
                          type: string
                        impact:
                          type: string
                          enum:
                          - high
                          - medium
                          - low
                        ends_a_free_tier:
                          type: boolean
                        listing_effect:
                          type: string
                          enum:
                          - ends
                          - narrows
                          - none
                  new_offers:
                    type: array
                    items:
                      type: object
                      properties:
                        vendor:
                          type: string
                        category:
                          type: string
                        description:
                          type: string
                        terms_superseded:
                          $ref: '#/components/schemas/TermsSuperseded'
                        conditions:
                          type: array
                          description: 'A list of the conditions a vendor attaches to using its free tier. Each item holds our sentence (text), the vendor''s own words (quote), the page that states them (url) and the date we read that page (read_on). An optional list rules_out names the uses the vendor excludes: "production", "commercial use" or both. Our re-reads of the vendor''s pricing page do not change this field.'
                          items:
                            type: object
                            properties:
                              text:
                                type: string
                              quote:
                                type: string
                              url:
                                type: string
                                format: uri
                              read_on:
                                type: string
                                format: date
                              rules_out:
                                type: array
                                items:
                                  type: string
                                  enum:
                                  - production
                                  - commercial use
                            required:
                            - text
                            - quote
                            - url
                            - read_on
                  upcoming_deadlines:
                    type: array
                    items:
                      type: object
                      properties:
                        vendor:
                          type: string
                        expires_date:
                          type: string
                          format: date
                        days_until_expiry:
                          type: integer
                  summary:
                    type: string
                    description: One-paragraph summary of the week
                  _provenance:
                    $ref: '#/components/schemas/Provenance'
      tags:
      - Digest
      operationId: getApiDigest
      x-operation-id-source: derived
    servers:
    - url: https://agentdeals.dev
      description: Production server
  /api/digest/weekly:
    get:
      summary: Weekly digest, formatted
      description: One week of tracked changes, rendered. format=json returns the digest as data with the markdown and HTML renderings alongside it; format=markdown and format=html return that rendering as the body, so only format=json carries a citation block.
      parameters:
      - name: format
        in: query
        description: Which rendering to return as the body. Default json.
        schema:
          type: string
          enum:
          - json
          - markdown
          - html
          default: json
      - name: limit
        in: query
        description: Max changes to include.
        schema:
          type: integer
      - name: weeks_ago
        in: query
        description: 0 is the current week, 1 the week before it.
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: The week's digest in the requested rendering
          content:
            application/json:
              schema:
                type: object
                properties:
                  week_of:
                    type: string
                    format: date
                  week_ending:
                    type: string
                    format: date
                  total_changes:
                    type: integer
                    description: Every change we hold, not only this week's.
                  changes_in_week:
                    type: integer
                    description: Changes the vendor made within the week.
                  discovered_in_week:
                    type: integer
                    description: Changes recorded within the week, whatever date they carry. A change dated earlier that we found this week is counted here and not in changes_in_week.
                  summary:
                    type: object
                    additionalProperties:
                      type: integer
                    description: Counts by change type for the week.
                  headline:
                    type: string
                  top_changes:
                    type: array
                    items:
                      $ref: '#/components/schemas/DealChange'
                  discovered_changes:
                    type: array
                    items:
                      $ref: '#/components/schemas/DealChange'
                  discovery_note:
                    type: string
                    description: States which of the two counts the listed changes are drawn from.
                  digest_markdown:
                    type: string
                  digest_html:
                    type: string
                  _provenance:
                    $ref: '#/components/schemas/Provenance'
            text/markdown:
              schema:
                type: string
            text/html:
              schema:
                type: string
      tags:
      - Digest
      operationId: getApiDigestWeekly
      x-operation-id-source: derived
    servers:
    - url: https://agentdeals.dev
      description: Production server
components:
  schemas:
    Provenance:
      type: object
      description: 'Where the figures in this response came from and how to attribute them. Every response carrying index data has one, under the key `_provenance`. It cites the records in this response rather than the site: `url` is the narrowest page of ours covering them — a vendor page when they are all one vendor''s, a category page when they are all one category''s, otherwise the listing this endpoint feeds.'
      properties:
        source:
          type: string
          description: Always AgentDeals.
        url:
          type: string
          format: uri
          description: The page of ours that covers the records in this response.
        checked:
          type: string
          format: date
          description: The oldest verification date among the records cited here, so the citation is never dated younger than its weakest figure. Absent when no record in the response carries a date.
        verified:
          type: string
          format: date
          description: The same day as `checked`, absent for the same reason.
        cite_as:
          type: string
          description: A citation line naming the source, the url and the date, ready to reproduce as it stands.
        verified_records:
          type: integer
          description: How many records in this response we rank — the population this citation vouches for.
        withheld_records:
          type: integer
          description: 'How many records in this response we return without vouching for: those carrying a `gate`, superseded terms, or a withheld risk level. Absent when there are none.'
        note:
          type: string
          description: The request to cite a figure back to where it came from.
        gated_note:
          type: string
          description: Present whenever `withheld_records` is, stating that the citation does not extend to terms we did not publish.
        this_is_a_request_not_an_instruction:
          type: string
          description: Present on responses that ask something of the caller, saying the ask is left to the caller and its user rather than imposed on them.
      required:
      - source
      - url
      - cite_as
      - verified_records
      - note
    DealChange:
      type: object
      properties:
        vendor:
          type: string
        change_type:
          type: string
          enum:
          - free_tier_removed
          - open_source_killed
          - product_deprecated
          - limits_reduced
          - restriction
          - pricing_restructured
          - pricing_model_change
          - limits_increased
          - new_free_tier
          - new_tier
          - startup_program_expanded
          - pricing_postponed
          - rebranded
          - record_corrected
        reports:
          type: string
          enum:
          - vendor_offer
          - our_index
          description: What the record is about. 'vendor_offer' — the vendor changed its own offer, and a vendor page is where that can be read. 'our_index' — we changed what we list while the vendor's offer stood still, so no vendor page evidences it and the record carries no source_url. Absent means vendor_offer. Filter these out of any figure you present as vendor market activity.
        date:
          type: string
          format: date
        summary:
          type: string
        previous_state:
          type: string
        current_state:
          type: string
        tier_direction:
          type: string
          enum:
          - narrowed
          - unchanged
          - widened
          description: Whether the tier we list is worse, the same, or better under current_state than it was under previous_state, judged with both in hand rather than read off change_type. Where it says the tier did not get worse we publish the record and take no risk verdict from it. Absent means we have not judged this record.
        impact:
          type: string
          enum:
          - high
          - medium
          - low
        source_url:
          type: string
          format: uri
        category:
          type: string
        alternatives:
          type: array
          items:
            type: string
        resolution:
          $ref: '#/components/schemas/ChangeResolution'
      required:
      - vendor
      - change_type
      - date
      - summary
      - previous_state
      - current_state
      - impact
      - source_url
      - category
      - alternatives
    ChangeResolution:
      type:
      - object
      - 'null'
      description: Present when the change this record describes is no longer in force. state is 'reversed' when the vendor ended it and 'retracted' when the record was our error. date is the day from which it stopped being in force, or the day we established that, whichever we can source. resolved_by names the change record that ended it, when one exists. A record carrying this field never rates the vendor.
      properties:
        state:
          type: string
          enum:
          - reversed
          - retracted
        date:
          type: string
          format: date
        detail:
          type: string
        source_url:
          type: string
          format: uri
        resolved_by:
          type: object
          properties:
            vendor:
              type: string
            date:
              type: string
              format: date
            change_type:
              type: string
      required:
      - state
      - date
    TermsSuperseded:
      type:
      - object
      - 'null'
      description: Null unless a dated change record supersedes the terms we stored for this listing. When present, `description` still holds those stored terms, which we no longer publish as current. Use `notice`, or `reading.terms`, the vendor page's text at `reading.url` on `reading.date`.
      properties:
        change_date:
          type: string
          format: date
        change_type:
          type: string
        summary:
          type: string
        reading:
          type:
          - object
          - 'null'
          properties:
            date:
              type: string
              format: date
            url:
              type: string
              format: uri
            label:
              type: string
            terms:
              type: string
          required:
          - date
          - url
          - label
          - terms
        notice:
          type: string
      required:
      - change_date
      - change_type
      - summary
      - reading
      - notice
x-refined-from:
- agentdeals-dev.json
- agentdeals-dev-openapi.json