Title: Metadata endpoint use and overview
Author: staff
Published: August 1, 2022
Last modified: July 20, 2026

---

 1. [API](https://docs.parse.ly/api/)
 2. [Endpoints](https://docs.parse.ly/api/api-endpoints/)
 3. Metadata endpoint use and overview

#  Metadata endpoint use and overview

#### Note

Anyone interested in using the /metadata endpoint should contact [Parse.ly Support](https://support.parse.ly/hc/en-us)
before doing so.

## POST /metadata/(metadata-type)

Updates the metadata for a post or video (depending on the specified `metadata-type`)
using the received `metadata` dictionary.

This endpoint uses a different `secret` value from our other endpoints for security
purposes. Please reach out to your account manager for details on how to identify
the write-only secret value that should be used for this endpoint.

Details on providing on-page metadata can be found [here](https://docs.parse.ly/metadata/).

> The **Content-Type** header must be set to `application/json` for the POST request
> to be properly received.

### Path Arguments

| metadata-type | One of `posts` OR `videos`. |

### Query Parameters

| secret | The write-only secret value. This differs from the standard secret value use for other endpoints. Please contact Support@parsely.com for details on how to identify the write-only secret value that should be used for this endpoint. | 
| metadata | The JSON object of metadata you would like to be written to our systems. The requisite format of this value is detailed below. |

### The Metadata Parameter

The `metadata` parameter should be a JSON object with the following schema:

| canonical_url | Canonical url for post or page. For page groups, like galleries, it should always point to the main page. | 
| urls | Urls that should be aliased to the `canonical_url` (the traffic for these urls and the `canonical_url` will be combined to form a single record) provided as a list. (e.g. `["https://test.com/slideshow/1", "https://test.com/slideshow/2"]`) **Note:** A HTTP/S url schema is required for these urls. | 
| page_type | The type of page between: `post`, `index`, `video`. See [“Distinguishing between posts and pages”](https://www.parse.ly/troubleshooting-faqs//integration/jsonld/#distinguishing-between-posts-and-pages) for more information on what differentiates and post and an index page. | 
| title | Page or video title. | 
| image_url | Url of the image associated with the page or video. | 
| pub_date_tmsp | Publication date, formatted as an ISO 8601 UTC timezone string. | 
| section | Section the page is a part of. (e.g. `"Politics"`). _Note that only 1 section value is supported_. Therefore, it is recommended that the top-level section or category is used and any sub-sections or child categories are added to tags. | 
| authors | Author(s) of the page or video, provided as a list. (e.g. `["Author 1", "Author 2"]`) | 
| tags | The list of keywords associated with the page or video will map to “Tags” in the Parse.ly dashboard. _Note that up to 100 keyword values are supported_. |

> It may take some time for metadata changes to be reflected in the Parse.ly Dashboard
> or API results due to caching.

## Example

We used the following methodology to send metadata for a PDF as discussed in our
[“Track Files” doc](https://docs.parse.ly/track-files/).

An example of a curl call you can execute in a command line is below.

    ```lang-shell
    curl -H "Content-Type: application/json" -X POST https://api.parsely.com/v2/metadata/posts -d '{"apikey": "test.com", "secret": "XXXXX", "metadata":{"pub_date_tmsp": "2018-11-30","title": "Fake Title","tags": ["Test"],"authors": ["API Metadata Endpoint"],"canonical_url": "https://blog.parsely.com/fake-url","page_type": "post","section": "Testing", "full_content": "Fake content for a fake article.", "language": "en"}}'
    ```

This request has the following url-encoded fields and values.

| apikey | `test.com` | 
| secret | `XXXXX` | 
| metadata | `{"pub_date_tmsp": "2018-11-30","title": "Fake Title","tags": ["Test"],"authors": ["API Metadata Endpoint"],"canonical_url": "https://blog.parsely.com/fake-url","page_type": "post","section": "Testing", "full_content": "Fake content for a fake article.", "language": "en"}` |

The metadata JSON object has the following fields and values.

| pub_date_tmsp | `"2018-11-30"` | 
| title | `"Fake Title"` | 
| tags | `["Test"]` | 
| authors | `["API Metadata Endpoint"]` | 
| canonical_url | `"https://blog.parsely.com/fake-url"` | 
| page_type | `"post"` | 
| section | `"Testing"` | 
| full_content | `"Fake content for a fake article."` | 
| language | `"en"` |

## Technical Caveats

**Values in the metadata will appear literally inside Parse.ly Analytics.** Remember
that _all metadata is case sensitive._ String values supplied here (specifically
title, authors, and section) as well as list values (specifically tags) will appear
in Parse.ly analytics _exactly_ as they are specified in the tag. As a result, make
sure to use proper capitalization and specify the values as you expect them to appear.
Values with variations (example: “John Smith” and “john smith”) will appear _separately_
in the Dashboard causing duplication and skewed data.

Last updated: July 20, 2026