Skip to main content

Distribution API

The Distribution API (DAPI) is a read-only service that delivers content created and managed in the FORGE Content Manager. It returns data in JSON format, making it straightforward to integrate across platforms and technologies.

Designed to be presentation-layer agnostic, DAPI supports maximum flexibility—allowing developers to retrieve and render content using any front-end framework (e.g., web, mobile, app) without relying on predefined templates or markup (e.g., HTML).

DAPI Base URL​

You can retrieve the base URL for DAPI from the FORGE back-office Administration panel, under the Distribution API section. The API URL field provides the endpoint needed to access DAPI.

API Structure​

A typical endpoint looks like:

https://dapi.acme.org/v2/content/en-us/stories/a-day-in-the-life

This URL is structured as follows:

  • https://dapi.acme.org: DAPI base URL
  • v2: API version (v1 and v2 supported; v2 recommended)
  • content: Indicates editorial content
  • en-us: The culture (language/locale) of the requested content
  • stories: The entity type
  • a-day-in-the-life: The slug (unique identifier) of the requested entity

If the slug is omitted, the endpoint returns a list of entities of the specified type.

Cultures​

The culture segment (e.g., en-US, it-IT) represents a language configured under System Languages in the FORGE Administration panel.

If a non-configured culture is requested, the API returns a 404.

Entity Types​

DAPI supports all published entity types, including:

  • stories
  • albums
  • photos
  • documents
  • editorial selections
  • tags

In addition, you can define Custom Entities in the FORGE back office. These work the same way as built-in entities.

Example: If a Video custom entity is available, its list URL would be:
https://dapi.acme.org/v2/content/en-us/videos
See Custom Entities and Entity by Slug for more.

Versions​

Use version v2 or higher. Version v1 is deprecated and will be removed.

Version v2 reduces payload sizes by omitting unnecessary metadata from list endpoints.

Endpoint Types​

DAPI provides three types of endpoints:

  • List: Returns a list of items of a given entity type
  • Detail: Returns full metadata for a specific item
  • System: Returns information for monitoring purpose or about configuration (e.g., photo formats)

Filtering​

DAPI supports a predefined set of filters available by default for all entity types:

  • tags: Filter content by tags
  • context: Filter by a tag set used as context
  • featured: Filter by promoted state
  • _id: Filter by slug

Taxonomy Filtering​

Filtering on tags and context supports two identifier types:

  • slug: Language-dependent; varies by culture
  • neutralSlug: Language-independent; shared across translations

See the examples section for a deeper dive on slugs.
Recommended: Use neutralSlug to ensure consistent filtering across languages.

Example:

GET https://dapi-base-url/v2/content/en-US/stories?tags.neutralSlug=football

Filtering by Extended Fields​

To filter on custom metadata, use extended fields. These must be included in a distribution index.

Example:

GET https://dapi-base-url/v2/content/en-US/stories?fields.provider=deltatre

Always prefix extended fields with fields.

You can combine multiple filters using &:

GET https://dapi-base-url/v2/content/en-US/stories?tags.neutralSlug=football&fields.provider=deltatre

Filters are combined using AND logic.

Advanced filtering​

In addition to the standard workflows, DAPI supports the possibility to filter the content based on data coming from external systems (such as Sports API) and that are connected to the ecosystem.

Searching for external tags​

FORGE supports two different kinds of tags:

  • free-text tags: These are the simplest type of tags that can be created directly from the back-office while writing the content
  • external tags: These tags are bound to an external data source (e.g. a Sports API) that can be organized in a hierarchy. When an entity is selected for tagging, a new tag is automatically created on the system containing all the references to the original entity on the external source. These kinds of tags are defined as imported on FORGE.

For example, let's assume that we have an external source that provides us a list of players that can be used for tagging and that we have tagged content with a specific player, resulting in the creation of a new imported tag. All imported tags keep the reference to the entity selected from the external data source with the following metadata on DAPI:

  • SourceName: the name of the source as configured on the Administration panel on FORGE back-office
  • SourceId: the unique identifier of the entity as defined by the external source and referenced by the imported tag

Let’s assume we are using “Roger Federer” to tag a story. Once we select the item proposed by the source of the external tags, a new imported tag is created and published in FORGE. This is the query to get its details:

GET https://dapi-base-url/v2/content/en-US/tags/roger-federer

In the URL above, api-base-url must be substituted with the absolute URL of the specific Distribution API instance and roger-federer is the imported tag's slug. The endpoint returns the externalSourceReference property:

{
    SourceName: "players",
    SourceId: "10234"
}

In addition to getting this tag by slug, you can obtain its detail by filtering by externalSourceReference. Specify the externalSourceReference filter as the query string parameter of the request, by passing the SourceName and SourceId values with the following syntax:

SourceName:SourceId

With the example data above, the request looks like this:

GET https://dapi-base-url/v2/content/en-US/tags?externalSourceReference=players:10234

Filtering entities by external tags​

FORGE supports searching content by using the externalSourceReference filter as explained in the previous section. This enables consumers to get all the items that have been tagged with data coming from an external source.

Let's assume, in the same scenario mentioned above, that we have a story talking about Roger Federer and we tagged it with the entity “Roger Federer” coming from the source of the external tags “players”.

Once published, we can search for it using the externalSourceReference filter on the tag object for the stories list endpoint as follow:

GET https://dapi-base-url/v2/content/en-US/stories?tags.externalSourceReference=players:10234

This query returns all stories that have been tagged with the external tag including the sourceName "players" and sourceId 10234.

Similarly to other query string parameters, it is possible to specify multiple externalSourceReference filters.

caution

When specifying the externalSourceReference filter multiple times, keep in mind that only items that are tagged with all the specified entities will be returned.

For example, a request like the following one returns only the stories that have been tagged with the two specified entities.

GET https://dapi-base-url/v2/content/en-US/stories?tags.externalSourceReference=players:10234&tags.externalSourceReference=players:71365

Complex Tagging​

Multiple tags can be used in a single query:

GET /v2/content/en-US/stories?tags.neutralSlug=football&tags.neutralSlug=final

Only content matching all specified tags will be returned.

Complex filters may degrade performance. When possible, split complex queries into smaller requests.

Equality Operators​

The Distribution API supports two types of filtering operators:

  • Equality: This is the default operator. It returns only items that exactly match the specified value.
  • Inequality: Indicated by the ! character. It returns only items that do not match the specified value.

To apply a "not equal to" filter, prefix the value with !.

Example: Retrieve all stories not tagged with football:

GET https://dapi-base-url/v2/content/en-US/stories?tags.neutralSlug=!football

These operators can be used on all filterable fields, including both built-in and extended fields.

Working with Boolean Fields​

When filtering boolean fields, keep in mind that the equality operator returns results only when the field is explicitly set to the specified value.

  • For example, filtering with false will return items where the boolean field is explicitly set to false.
  • It will not return items where the field is null or not set at all.

To include both false and null values in the results, use the inequality operator to exclude true:

GET https://dapi-base-url/v2/content/en-US/stories?fields.showAdv=!true

This returns all stories where the showAdv field is either set to false or not explicitly set.

Range Operator ($range)​

Use the $range operator to filter by:

  • numeric
  • date-time
  • boolean fields

Syntax:

fieldName=$range(value1,value2)
  • value1: Minimum inclusive value
  • value2: Maximum inclusive value

Example:

GET /v2/content/en-US/photos?fields.shootingDate=$range(2020-06-01T00:00:00Z,2020-07-31T23:59:59Z)

Use ISO 8601 for date-time values.
If only one bound is needed, omit the other:

  • Greater than: $range(2020-01-01,)
  • Less than: $range(,2020-01-01)

Incorrect range order (e.g., max before min) returns a 200 OK with empty results.

List Availability​

From FORGE 4.14.0 onward, editors can set content availability on lists.

Availability is controlled using the _listAvailability query parameter:

  • 0 = Public
  • 1 = Unlisted

Examples:

GET /v2/content/en-US/stories?_listAvailability=1  // only unlisted
GET /v2/content/en-US/stories?_listAvailability=0  // only public
GET /v2/content/en-US/stories?_listAvailability=$range(0,1) // all

See Controlling Availability on Lists

Geo-Location Filtering ($near)​

DAPI supports filtering by proximity using $near.

Setup:

  • Add a field with coordinates
  • Index it using a MongoDB 2dsphere index

Syntax:

GET /v2/content/en-US/photos?fields.geoLocation=$near(40.705903,-73.996499,1000)

Where:

  • First two values are longitude, latitude
  • Third value is distance in meters

Sorting is by proximity unless overridden with a custom sort.

Full-Text Search ($text)​

DAPI allows full-text filtering using the $text operator.

Requirements:

  • A distribution index must include all fields to be searched

Example:

GET /v2/content/en-US/stories?$text=Usain%20Bolt

Always URL-encode the search term.

Limitations​

  • Only complete word matches are supported
  • No substring or partial matching
  • Based on MongoDB's text search capabilities

Not recommended for B2C.
Ideal for internal/B2B tools with lightweight search requirements.

$text results are ranked by relevance, unless overridden by a sort.

Pagination​

DAPI supports standard pagination via:

  • $skip: Number of items to skip
  • $limit: Maximum number of items to return

Defaults:

$skip=0&$limit=25

Subsequent pages:

$skip=25&$limit=25  // page 2
$skip=50&$limit=25  // page 3

Pagination Metadata​

The API includes:

  • maxItems: Maximum size per page (default: 100)
  • nextUrl: Pre-computed URL for the next page
  • previousUrl: URL for previous page (from page 2 onward)

Recommended: Use the smallest $limit possible to reduce payload and bandwidth.

Sorting​

Content is sorted by default using:

  1. featured: Featured content appears first
  2. contentDate: Newest first

To sort by a different field, use the $sort parameter.

Example:

GET /v2/content/en-US/photos?$sort=fields.copyright
GET /v2/content/en-US/photos?$sort=fields.copyright:asc

Only one sort condition is allowed.
Sorting is case-sensitive.
Default direction comes from the distribution index.

Encoding​

When making requests to DAPI:

  • Use UTF-8 as the charset
  • Set the Content-Type header to:
Content-Type: application/json; charset=utf-8