Associated Press Content API

openapi: 3.2.0
info:
  title: Associated Press AP Media Account Content API
  description: AP's next generation content API.
  version: '2.2'
servers:
- url: //api.ap.org/media/v
security:
- apikey: []
  apikeyUrl: []
tags:
- name: Content
paths:
  /content/{item_id}:
    get:
      tags:
      - Content
      summary: Associated Press Single item metadata lookup
      description: 'Fetch the ''contentitem'' object for a single piece of content by its Item ID.

        '
      parameters:
      - name: item_id
        in: path
        description: 'The itemid of the desired piece of content

          '
        required: true
        schema:
          type: string
      - name: include
        in: query
        description: Comma separated list of fields to include from the response
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: exclude
        in: query
        description: Comma separated list of fields to exclude from the response
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: pricing
        in: query
        description: Whether to include pricing information with the results
        schema:
          type: boolean
      - name: in_my_plan
        in: query
        description: Specifying in_my_plan=true in the request returns only those associations of the content item that do not incur any additional cost to download.
        schema:
          type: boolean
      - name: format
        in: query
        description: The desired response format
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contentresponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '401':
          description: Invalid Auth
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
      security:
      - apikey: []
      - apikeyUrl: []
  /content/search:
    get:
      tags:
      - Content
      summary: Associated Press Search for AP content
      description: 'Searches AP Content and returns `ContentItem` objects.

        Use the optional query param of **q** to filter the set of content

        '
      parameters:
      - name: q
        in: query
        description: Your query
        allowEmptyValue: true
        schema:
          type: string
      - name: include
        in: query
        description: Comma separated list of fields to include from the response
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: exclude
        in: query
        description: Comma separated list of fields to exclude from the response
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: sort
        in: query
        description: Your desired sorting criteria
        schema:
          type: string
          default: _score:desc
      - name: page
        in: query
        description: The desired page number. Page numbers begin at 1
        schema:
          type: string
      - name: page_size
        in: query
        description: Number of items to return per page
        schema:
          type: integer
      - name: pricing
        in: query
        description: Whether to include pricing information with the results
        schema:
          type: boolean
      - name: in_my_plan
        in: query
        description: Specifying in_my_plan=true in the request returns only those items that do not incur additional cost to download. Additionally, items returned include only those associations that do not incur any additional cost to download.
        schema:
          type: boolean
      - name: session_label
        in: query
        description: Attach an informational label to this session
        schema:
          maxLength: 48
          minLength: 1
          pattern: ^[a-zA-Z0-9_. -]*$
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/searchresponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '401':
          description: Invalid Auth
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
      security:
      - apikey: []
      - apikeyUrl: []
  /content/feed:
    get:
      tags:
      - Content
      summary: Associated Press Receive a feed of incoming AP content
      description: 'Receive a feed of AP Content as ''contentitem'' objects.

        Use the optional query param of **q** to filter the set of content

        '
      parameters:
      - name: q
        in: query
        description: Your query
        allowEmptyValue: true
        schema:
          type: string
      - name: include
        in: query
        description: Comma separated list of fields to include from the response
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: exclude
        in: query
        description: Comma separated list of fields to exclude from the response
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: page_size
        in: query
        description: Number of items to return per page
        schema:
          type: integer
      - name: pricing
        in: query
        description: Whether to include pricing information with the results
        schema:
          type: boolean
      - name: in_my_plan
        in: query
        description: Specifying in_my_plan=true in the request returns only those items that do not incur additional cost to download. Additionally, items returned include only those associations that do not incur any additional cost to download.
        schema:
          type: boolean
      - name: with_monitor
        in: query
        description: Apply the named Monitor to subsequent calls for this session
        schema:
          maxLength: 24
          minLength: 4
          pattern: ^[a-zA-Z0-9_.-]*$
          type: string
      - name: session_label
        in: query
        description: Attach an informational label to this session
        schema:
          maxLength: 48
          minLength: 1
          pattern: ^[a-zA-Z0-9_. -]*$
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/feedresponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '401':
          description: Invalid Auth
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
      security:
      - apikey: []
      - apikeyUrl: []
  /content/rss:
    get:
      tags:
      - Content
      summary: Associated Press Retrieve a list of available RSS XML feeds entitled to your plan.
      description: '(Successful responses always in XML)

        '
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rssresponse'
            text/xml:
              schema:
                $ref: '#/components/schemas/rssresponse'
        '304':
          description: Successful response, Not Modified
          content: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
            text/xml:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '401':
          description: Invalid Auth
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
            text/xml:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
            text/xml:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
            text/xml:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
            text/xml:
              schema:
                $ref: '#/components/schemas/errorresponse'
      security:
      - apikey: []
      - apikeyUrl: []
  /content/rss/{rss_id}:
    get:
      tags:
      - Content
      summary: Associated Press Receive a RSS feed of latest AP content
      description: 'Receive a RSS feed of latest AP Content for a Product (RSS) Id.

        Use optional **include** and **exclude** to tailor the response.

        '
      parameters:
      - name: rss_id
        in: path
        description: "The product ID for the desired RSS feed (see /content/rss) \n"
        required: true
        schema:
          type: integer
      - name: include
        in: query
        description: Comma separated list of fields to include from the response
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: exclude
        in: query
        description: Comma separated list of fields to exclude from the response
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: page_size
        in: query
        description: Number of items to return per page
        schema:
          type: integer
      responses:
        '200':
          description: Successful response
          content: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
            text/xml:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '401':
          description: Invalid Auth
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
            text/xml:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
            text/xml:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
            text/xml:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
            text/xml:
              schema:
                $ref: '#/components/schemas/errorresponse'
      security:
      - apikey: []
      - apikeyUrl: []
  /content/ondemand:
    get:
      tags:
      - Content
      summary: Associated Press Receive a feed of AP content items which have been sent to your organization's OnDemand queue.
      description: 'Receive a feed of ''contentitem'' objects which have been sent to your organization''s OnDemand queue.

        '
      parameters:
      - name: consumer_id
        in: query
        description: 'A user defined identifier for the consumer of this feed.

          Each unique consumer ID will receive every item in your organization''s OnDemand queue once.

          If not specified, the API key of the request will be used.'
        schema:
          type: string
      - name: queue
        in: query
        description: The ID of the desired queue.
        schema:
          type: string
      - name: include
        in: query
        description: Comma separated list of fields to include from the response
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: exclude
        in: query
        description: Comma separated list of fields to exclude from the response
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: page_size
        in: query
        description: Number of items to return per page
        schema:
          type: integer
      - name: pricing
        in: query
        description: Whether to include pricing information with the results
        schema:
          type: boolean
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/feedresponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '401':
          description: Invalid Auth
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse'
      security:
      - apikey: []
      - apikeyUrl: []
components:
  schemas:
    sessionMonitorResponse:
      allOf:
      - type: object
        properties:
          monitor:
            type: object
            properties:
              name:
                type: string
                description: Name of assigned Monitor
              label:
                type: string
                description: Optional session_label
              enabled:
                type: boolean
                description: true if the overall session is elligible for monitoring
              last_checked:
                type: string
                description: When an eligible session monitor was last checked
                format: date-time
              enable_session_monitor:
                type: string
                description: Call this link to enable monitoring for this session
              disable_session_monitor:
                type: string
                description: Call this link to disable monitoring for this session
              conditionStatus:
                type: object
                properties:
                  idleFeed:
                    $ref: '#/components/schemas/conditionStatus'
                  quality:
                    $ref: '#/components/schemas/conditionStatus'
              feed_count:
                type: integer
                description: count of feed requests made in this session
            description: High level monitor status for monitored sessions
    contentitem:
      type: object
      properties:
        uri:
          type: string
          description: The identifier for this content item expressed as a URI.
        altids:
          required:
          - itemid
          type: object
          properties:
            itemid:
              type: string
              description: A unique content item ID. For items with multiple versions, remains the same for the initial version and each subsequent revision. For example, if a news story is written and rewritten several times as new information is uncovered, this ID value remains the same for each rewrite because it points to the chain of revised stories, and not an individual version.
            etag:
              type: string
              description: ' A short digest (also known as checksum or hash) of the item''s metadata. Useful for deduplication and conditional requests.'
            friendlykey:
              type: string
              description: A human-readable ID of a content item. For video, this is the AP Archive story number.
            videoid:
              type: string
            transref:
              type: string
              description: Transmission Reference Number; the alphanumeric identifier (or file name) associated with a story or photo.
            graphicsbankid:
              type: string
            'referenceid ':
              type: string
          description: Alternative IDs of a content item
        foreignkeys:
          type: array
          items:
            type: object
        version:
          type: integer
          description: "The content item version number: 0 for the initial version, 1 for the first version, 2 for the second version and so on. The higher the number, the more recent the content item's version. \n - For text stories, this is the version of the story revision. \n - For other media types (for example, photos, graphics and video), this is the version of the item metadata; for example, a photo caption. Typically, significant changes to the binary asset (such as a photo) are published as a new content item."
        type:
          type: string
          description: 'The generic news type of this content item: text, picture, graphic, audio or video.'
          enum:
          - text
          - picture
          - graphic
          - audio
          - video
        profile:
          type: string
          description: The type of information contained in the news item (also known as 'ItemContentType'); for example, Spot Development, Advisory and Weather Forecast. Currently, content types are applied to text and audio news items. For a complete list of values, see [Profile (ItemContentType)](https://api.ap.org/media/v/docs/api/#t=AP_Classification_Metadata.htm%23Profile__ItemContentType_).
        urgency:
          type: integer
          description: The editorial urgency of the content from 1 to 8. 1 represents the highest urgency, 8 the lowest.
        editorialpriority:
          type: string
        language:
          maxLength: 2
          minLength: 2
          type: string
          description: The two-letter code of the language that the news item is written in; for example, en or es.
        versioncreated:
          type: string
          description: The date and time when this version of the content item was published.
          format: date-time
        firstcreated:
          type: string
          description: "The date and time when the first version of the item was created.\n - For photos and video, this is the date and time when the content for the item was created. For example, a photo taken at a Sunday night game and published on Monday morning would carry the firstcreated value from Sunday, and the versioncreated value for the photo entry would be from Monday.\n - For GraphicsBank items, this is the date of the news event that the graphic illustrates."
          format: date-time
        embargoed:
          type: string
          description: The date and time before which all versions of the content item are embargoed (if absent, this item is not embargoed).
          format: date-time
        editorialrole:
          type: string
        fixture:
          type: object
          properties:
            name:
              type: string
              description: The name of the fixture; for example, "Film Reviews".
            code:
              type: string
              description: The code for the fixture in AP systems.
          description: Named sets of regularly occurring content or features with a predictable focus; for example, "Financial Impact," "Film Reviews," "10 Things to Know," "Sports Briefs." For more information, see a complete list of [AP Fixtures](https://api.ap.org/media/v/docs/api/APFixtures.xls).
        pubstatus:
          type: string
          description: "The publishing status of the content item, which contains information regarding the item's ability to be distributed to news consumers. This value is usable by default. \n - usable: This content item may be distributed to news consumers in publishing forms that do not violate your agreement with the AP and copyright information contained in the content item and its metadata.\n - embargoed (the same as Hold-For-Release): Do not distribute an embargoed content item to news consumers until the release date-time found in embargoed has occurred.\n - withheld: Do not distribute this content item to news consumers because it contains questionable information. Any distributed form of the content item must be recalled.\n - canceled (the same as Kill): Do not distribute this content item to news consumers because it contains erroneous information. Any distributed form of the content item must be recalled.\n\n**Important**\nDo not use the pubstatus property alone to determine a content item's publishing status. Check the values of ednote, embargoed and editorialtypes to determine whether the content may be published."
          enum:
          - usable
          - embargoed
          - withheld
          - canceled
        ednote:
          type: string
          description: Editorial instructions for processing the item. Do not distribute this information to news consumers.
        editorialtypes:
          type: array
          description: "The editorial condition of the content item revision:\n - For text: Add, Advisory, Clarification, Corrective, Disregard, HoldForRelease, Kill, Lead, Writethru, Takes or Withhold.\n - For photos: Correction, Elimination, Kill or Withhold.\n - For video: Kill"
          items:
            type: string
            enum:
            - Add
            - Advisory
            - Clarification
            - Corrective
            - Disregard
            - HoldForRelease
            - Kill
            - Lead
            - Writethru
            - Takes
            - Withhold
            - Correction
            - Elimination
        signals:
          type: array
          description: Machine-readable instructions for processing the content item. [Learn more](https://api.ap.org/media/v/docs/api/index.html#t=Content_Metadata_Fields.htm%23MiniTOCBookMark19)
          items:
            type: string
            enum:
            - APWhollyOwned
            - explicitcontent
            - Test
            - Derived
            - DerivedLatest
            - isnotdigitized
            - NewsroomReady
            - newscontent
            - ConsumerReady
            - singlesource
            - whitelisted
        title:
          type: string
          description: A short publishable value containing the title of the current version of the content item.
        headline:
          type: string
          description: A brief synopsis of the current version of the content item. For photos, this field may contain the names of the people featured in the photo.
        headline_extended:
          type: string
        headline_seo:
          type: string
        slugline:
          type: string
          description: A non-publishable sequence of tokens associated with the content that is used as a short human-readable identifier for the content item and version.
        description_summary:
          type: string
          description: The story summary.
        bylines:
          type: array
          description: The party who created or contributed to the content (if available and not captured in the photographer, captionwriter, producer or editor properties); for example, a writer (for text stories), an editor (for photos) or a speaker (for audio). To learn more, see [About Bylines](https://api.ap.org/media/v/docs/api/index.html#t=About_Bylines.htm).
          items:
            required:
            - by
            type: object
            properties:
              code:
                type: string
                description: A code identifying the creator or contributor.
              parametric:
                type: string
                description: Additional information about the creator's or contributor's role.
              by:
                type: string
                description: The name(s) of the content creator(s) and/or contributors.
              title:
                type: string
                description: The title of the party referenced in the byline.
        producer:
          required:
          - name
          type: object
          properties:
            name:
              type: string
              description: The name of the content producer.
          description: A party that created or enhanced the content of this item.
        photographer:
          required:
          - name
          type: object
          properties:
            code:
              type: string
            name:
              type: string
            title:
              type: string
        located:
          type: string
          description: The location where the news event or subject described or depicted by the content occurred.
        datelinelocation:
          type: object
          properties:
            city:
              type: string
              description: The location's city.
            countrycode:
              type: string
              description: An abbreviated form of the location's country.
            countryname:
              type: string
              description: The full name of the location's country.
            countryareacode:
              type: string
              description: The location's country area. A country area is a large-scale division within a country; for example, a U.S. state or Canadian province.
            countryareaname:
              type: string
              description: The full name of the location's country area. A country area is a large-scale division within a country; for example, a U.S. state or Canadian province.
            geometry_geojson:
              required:
              - coordinates
              - type
              type: object
              properties:
                type:
                  type: string
                  description: 'Geometry type: Point.'
                  enum:
                  - Point
                coordinates:
                  type: array
                  description: Longitude and latitude of the location.
                  items:
                    type: number
              description: A [GeoJson](http://geojson.org/) object holding geo data of this place.
          description: Contains detailed, uniform and machine-usable metadata about the location where the news event or subject described or depicted by the content occurred.
        copyrightnotice:
          type: string
          description: Any necessary copyright notice for claiming the intellectual property for the content.
        usageterms:
          type: array
          description: Rights information and usage limitations associated with the publication, including any special restrictions. In addition to the special restrictions in usageterms, make sure to check for any additional use information and editorial notes in ednote and in the video script and/or shotlist.
          items:
            type: string
        keywords:
          type: array
          description: A displayable set of keywords relevant to a publication that can be used to expedite content searching in your own system.
          items:
            type: string
        outcue:
          type: string
          description: The last spoken words heard on the audio, used to help editors and news anchors construct program scripts and resume speaking after the broadcast of an audio file.
        provider:
          type: string
          description: The name of the provider.
        infosource:
          type: array
          description: A party (person or organization) that originated, modified, enhanced, distributed, aggregated or supplied the content or provided some information used to create or enhance the content. This information may be different from the copyright and provider.
          items:
            required:
            - name
            type: object
            properties:
              name:
                type: string
                description: The name of the infosource.
              type:
                type: string
                description: The source party's type in AP systems.
        links:
          type: array
          description: Contains external links; such as canonical links to full stories in AP News Archive. You can use canonical links to redirect web users to AP News Archive after your right to host AP content on websites expires at 30 days.
          items:
            required:
            - href
            - rel
            type: object
            properties:
              href:
                type: string
                description: The URL for accessing the external content.
              rel:
                type: string
                description: The type of link to external content; for example, *canonical*.
        person:
          type: array
          description: Individual human beings with a relationship to the content, such as named people mentioned in the content.
          items:
            required:
            - creator
            - name
            - r

# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/associated-press/refs/heads/main/openapi/associated-press-content-api-openapi.yml