Add meta with the API

You can add various meta information to any file in your Sirv account.

Meta data is easily searchable and can help you categorize your files to create fast workflows and integrate with your files with other programs/services which you use.

Types of meta data

The Sirv API lets you add these types of meta:

• description - max length 1024 characters (used for img alt text)
• title - max length 256 characters
• tags - max 50 tags, up to 32 characters each
• approval - max length 256 characters
• Product meta:
  • id - max length 256 characters
  • name - max length 256 characters
  • brand - max length 256 characters
  • category1 - max length 256 characters
  • category2 - max length 256 characters

If you need more meta data fields, please describe your requirements to the Sirv customer success team.

How to add meta

Meta can be added in 3 ways: API request; CSV upload; or in my.sirv.com.

Add meta via API

First connect to the Sirv API and get a token. Then run any of these commands to set meta:

• Set meta description
• Set meta title
• Set meta tags
• Set approval flag
• Set product meta

Those documentation links provide an example response and example scripts in: cURL, Python, Node.js, JavaScript, Java, PHP, Ruby, Swift, Go, C#.

Add meta via CSV

If you're uploading files to Sirv via a CSV list, fields from your CSV can be added as meta data.

Learn how to upload files from a CSV.

Add meta via my.sirv.com

It's easy to add meta to one file at a time. Go to any file in your account at my.sirv.com and on the right side you can view and edit the file meta.

How to retrieve meta

Meta can be obtained in 4 ways: API request; HTTP request; CSV download; or in my.sirv.com.

Get meta via API

First connect to the Sirv API and get a token.

To check the meta of one file at a time, run any of these commands:

• Get meta description
• Get meta title
• Get meta tags
• Get approval flag
• Get product meta

To check the meta of lots of files, submit an API search and then scroll through results.

Get meta via HTTP

Simply send an HTTP request for the file, with ?info appended to the URL. It will return the entire file meta in JSON, including meta from your original file.

Example:

https://demo.sirv.com/example.jpg?info

Scroll towards the end to see this meta:

    "tags": [
      "tiger",
      "sleeping"
    ],
    "description": "Sleeping tiger",
    "title": "Example image",
    "product": {
      "id": "TIG001",
      "name": "Tiger close-up",
      "brand": "Animal Prints",
      "category1": "Animals",
      "category2": "Big cats"
    },

You can also request that data in JSONP format. Add &callback=abc to the URL.

Example:

https://demo.sirv.com/example.jpg?info&callback=abc

Get meta via CSV

It's easy to export a list of files as a CSV from your account. This is a good way to get meta for a large number of files. The CSV will contain columns for title, description, tags and any custom meta. Product meta can be added - please ask our customer success team if you need this.

Get meta via my.sirv.com

Simply go to the file preview page for any file in your account at my.sirv.com. Meta data is shown to the right.

Sanitise your input

If you're adding meta via a script and cannot trust the source, you should sanitise the inputs, following standard best-practice. For example, strip content that contains any of the following:

• <script
• onclick
• onload
• onmousemove etc.

Try the API

A relatively quick way to try the API is with Sirv's Postman API collection. In Postman, go to the section Sirv REST API > Files and you will see options to set or get meta description, title, tags, product meta and approval meta. In the Params section, set the path to your Sirv image; in the Body section, set the meta values you wish to apply.

API limit

Your account can use a finite number of API requests per hour. Meta requests count towards your total hourly limit. Your current usage is shown on the Usage page of your account.

If you reach your limit, pause until the hourly limit refreshes. Every API request you submit will return a response containing the number of remaining requests and the refresh time.

It will help you to troubleshoot any issue if you save each API response in a log.

Create your Sirv account

If you don't have a Sirv account yet, create your account today.

Get expert help

For help using meta data and the Sirv API, please contact the Sirv customer success team.