Skip to content

API: Custom metadata setup and options

Though the API attempts to provide all the data and metadata you may need for rendering site features, there may occasionally be pieces specific to you that would be useful to have in the API, that are not available in’s data model. For these situations, we support a parsely-metadata META tag on your article pages, which can add arbitrary metadata to existing posts.


Custom metadata values are only returned in API queries and can not be made available in the dashboard.

Add a META tag to your page with the name “parsely-metadata” and a content field which is a serialized (and, as needed, quote-escaped) JSON string. For example:

<meta name='parsely-metadata' content='{"type": "feature", "image_url": ""}'>

JSON-LD configuration

Alternatively, you can add the metadata as a field to your json-ld script tag:

metadata(Optional) Arbitrary data to attach to post. Must be a valid JSON string. Note that this property is not part of official schemas.
<script type="application/ld+json">
  "@context": "",
  "@type": "NewsArticle",
  "headline": "Zipf's Law of the Internet: Explaining Online Behavior",
  "url": "",
  "thumbnailUrl": "",
  "datePublished": "2013-08-15T13:00:00Z",
  "articleSection": "Programming",
  "creator": ["Alan Alexander Milne"],
  "keywords": ["statistics","zipf","internet","behavior"],
  "metadata": "{"type": "feature", "image_url": ""}"

Escape double quotes in JSON item values. Double quotes should be escaped with a backslash symbol like this: \".

Once that is done you can notify the team, who can trigger recrawling of your site — this will fetch all post pages to sync up the parsely-metadata field with our database. This is to ensure old posts are backfilled with this metadata.

After that you will start receiving the metadata you sent in the metadata field in API. All data in your META tag will simply be passed through, as-is. Note that these values won’t be displayed in your dashboard.

Technically, the metadata field can store any arbitrary string, but we recommend you format it as JSON. Also, this string is limited to 2,000 characters — if it is longer than that, it is ignored.

Last updated: May 31, 2024