Yext Content API API

openapi: 3.0.0
info:
  title: Yext Admin Account Settings Content API API
  version: '2.0'
servers:
- url: https://api.yextapis.com/v2
security:
- api_key: []
- api-key: []
tags:
- name: Content API
paths:
  /accounts/{accountId}/content/{endpoint}/{ids}:
    get:
      operationId: contentGet
      parameters:
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/endpoint'
      - $ref: '#/components/parameters/contentDocIds'
      - $ref: '#/components/parameters/v'
      tags:
      - Content API
      summary: 'Content: Get'
      description: Retrieve records by ID from a Content Endpoint
      responses:
        '200':
          $ref: '#/components/responses/StreamsResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{accountId}/content/{endpoint}:
    get:
      operationId: contentList
      parameters:
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/endpoint'
      - $ref: '#/components/parameters/v'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/pageToken'
      tags:
      - Content API
      summary: 'Content: List'
      description: 'List records from a Content Endpoint


        Content API provides the ability for a user to filter and sort records

        by the contents of an indexed field. The filters and sorting parameters can

        be provided as query parameters, in addition to the query parameters

        documented here. If no filters are provided, the API returns all the records

        (with pagination).


        For example, with the parameter **`name=Alice`**, only records where the

        field **`name`** has value **`Alice`** will be returned.


        Similarly, adding the parameters **`name__in=Alice`** and **`name__in=Bob`**

        will result in records with **`name`** equal to **`Alice`** OR **`name`**

        equal to **`Bob`** being returned.


        ### Filters


        Filters are supported on Text, Numeric, Date and DateTime fields, although

        not all filters are supported by all fields. It is also possible to filter

        on an array of strings, or a string field nested in an array of objects. In

        this case, the record will be present in the response if one of the field

        values in the array matches the filter.


        Multiple filters on different fields and different filter types can be

        combined in the same query. An indexed field with an object can be filtered

        by using the dot notation, for example, **`address.city=Brooklyn`**.


        A number of different types of filters are supported.


        #### Equals


        This can be specified as simple query parameter.


        Supported Types: Text, Numeric, Date, DateTime, Fields within Arrays.


        *Example:*

        Adding **`&name=Alice`** as a query parameter will return records where the

        name field matches Alice.



        #### Not Equals


        This can be specified with the **`neq`** modifier to the query parameter

        key.


        Supported Types: Text, Numeric, Date, DateTime, Fields within Arrays.


        *Example:*

        Adding **`&name__neq=Alice`** as a query parameter will return records where

        the name field does not match Alice.


        #### Equals Any Of


        This is basically an `OR` clause for Equals on a given field. This can be

        specified with the **`in`** modifier to the query parameter key.


        Supported Types: Text, Numeric, Date, DateTime, Fields within Arrays.


        *Example:*

        Adding **`&name__in=Alice&name__in=Bob`** as a query parameter will return

        records where the name field matches either Alice or Bob.


        #### Comparison


        The following comparison filters are supported:

        * Greater Than with the modifier `gt`

        * Greater Than Or Equals with the modifier `gte`

        * Less Than with the modifier `lt`

        * Less Than Or Equals with the modifier `lte`


        Supported Types: Numeric, Date, DateTime.


        *Example:*

        Adding **`&createdDate__gt=2020-11-11&rating__gte=4`** as a query parameter

        will return records where the `createdDate` is after `2020-11-11` and the

        `rating` field has a value greater than or equal to `4`.


        #### GeoSearch


        Supports filtering to records for which the specified field is within the supplied radius to the supplied latitude and longitude.


        Supported Types: Coordinates (ex: `yextDisplayCoordinate`, `displayCoordinate`, etc.).


        GeoSearch queries are constructed by appending a `__geo` comparator to a coordinate field in the request. The details of the GeoSearch must then be included, comma separated, as part of the query value, optionally surrounded by parantheses.


        The following parameters are supported:

        * The latitude of the point to geosearch from, specified as `lat`

        * The longitude of the point to geosearch from, specified as `lon`

        * The numeric radius from the point which results will be filtered to, specifed as `radius`

        * The unit of measurement for the radius, specified as `unit`. One of `km`, `mi`, `m`, `ft`. Defaults to `mi`


        *Example:*

        Adding **`&yextDisplayCoordinate__geo=(lat:40.740,lon:-73.987565,radius:50,unit:km)`** as a query parameter

        will return records where the `yextDisplayCoordinate` field on the entities is within 50 km of the provided latitude and longitude.


        Like all other filters, the field which is being geosearched upon must be specified in the `fieldIndexes` of the endpoint definition.


        ### Sorting


        Content Endpoints support sorting by an indexed field. This can be enabled

        by adding the `$sortBy` query parameter with field name as the value.

        Optionally, the modifiers `asc` and `desc` can be added to indicate

        sorting by ascending and descending orders respectively. If no modifier is

        specified, the results will be returned in descending order.


        Currently, sorting is only supported on a single field per request.


        *Example:*

        Adding **`&$sortBy__desc=createdDate`** as a query parameter will return

        records with the most recent `createdDate` first.


        ### Additional Notes on Supported Types


        Indexes are supported on String, Numeric, Date and DateTime types. The set

        of supported filters for each type is documented in the previous section.


        #### String


        Content Endpoints support indexing UTF-8 strings with a maximum length of

        256 characters.


        #### Date and DateTime


        * The timezone information on a DateTime, if present, will be stripped away

        during indexing, without converting the time to another timezone.

        * For indexing, the system expects to get [RFC3339 DateTime

        format](https://datatracker.ietf.org/doc/html/rfc3339) for DateTimes and

        `YYYY-MM-DD` for Dates.

        * For querying, API accepts the following formats: `YYYY-MM-DD`,

        `YYYY-MM-DDTHH`, `YYYY-MM-DDTHH:MM` and `YYYY-MM-DDTHH:MM:SS`.

        '
      responses:
        '200':
          $ref: '#/components/responses/StreamsResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  responses:
    StreamsResponse:
      description: Content Response
      content:
        application/json:
          schema:
            title: ContentResponse
            type: object
            properties:
              meta:
                $ref: '#/components/schemas/ResponseMeta'
              response:
                type: object
                required:
                - count
                properties:
                  count:
                    type: integer
                    description: '

                      Total number of documents that meet the filter criteria.

                      '
                  docs:
                    type: array
                    description: Documents containing the data for the relevant Content Endpoint and request.
                    items:
                      type: object
                  nextPageToken:
                    $ref: '#/components/schemas/NextPageToken'
    ErrorResponse:
      description: Error Response
      content:
        application/json:
          schema:
            title: ErrorResponse
            type: object
            properties:
              meta:
                $ref: '#/components/schemas/ResponseMetaWithError'
              response:
                type: object
  parameters:
    contentDocIds:
      name: ids
      in: path
      required: true
      schema:
        type: array
        items:
          type: string
      style: simple
      description: 'The Content records to get. Multiple record IDs can be provided separated by commas.

        '
    v:
      name: v
      in: query
      required: true
      schema:
        type: string
      description: A date in `YYYYMMDD` format.
    endpoint:
      name: endpoint
      in: path
      required: true
      schema:
        type: string
      description: The ID of the Content Endpoint to query.
    accountId:
      name: accountId
      in: path
      required: true
      schema:
        type: string
    pageToken:
      name: pageToken
      in: query
      schema:
        type: string
      required: false
      description: 'If a response to a previous request contained the **`nextPageToken`** field, pass that field''s value as the **`pageToken`** parameter to retrieve the next page of data.

        '
    limit:
      name: limit
      in: query
      schema:
        type: integer
        default: 10
        maximum: 50
      description: Number of results to return.
  schemas:
    NextPageToken:
      type: string
      description: "This field is only included if there is an additional page of data to display. To retrieve the next page of data, pass this field's value as the **``pageToken``** parameter in a subsequent request. \n"
    ResponseMeta:
      type: object
      properties:
        uuid:
          type: string
          example: 4f72b877-e2d0-4de4-9324-b9cf2c03e1a0
          description: Unique ID for this request / response.
    ResponseError:
      type: object
      properties:
        name:
          type: string
        code:
          type: integer
          description: 'Code that uniquely identifies the error or warning.

            '
        type:
          type: string
          enum:
          - FATAL_ERROR
          - NON_FATAL_ERROR
          - WARNING
        message:
          type: string
          description: Message explaining the problem.
    ResponseMetaWithError:
      allOf:
      - $ref: '#/components/schemas/ResponseMeta'
      - type: object
        properties:
          errors:
            type: array
            description: List of errors and warnings.
            items:
              $ref: '#/components/schemas/ResponseError'
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: query
    api-key:
      type: apiKey
      name: api-key
      in: header