The Image Relay API allows IR users to access many Image Relay features through a JSON RESTful web interface. Not all plans have access to the API, generally just Professional and Enterprise plans. For details about API access on your plan please contact

More detailed information on our API can be found on GitHub.

Making a Request

All requests start with https://[company url]

In curl a request would look like this:

curl -u user:pass -H 'User-Agent: MyApp ('

If you are sending data to the API, include the Content-Type header and the data as JSON.

curl -u username:password \ -H 'Content-Type: application/json' \ -H 'User-Agent: MyApp (' \ -d '{ "name": "New Catalog" }' \


To test things out and get started, you can use HTTP Basic authentication with the IR API. In production, though, you should use an API Key for authentication. That way you don't have to worry about storing Image Relay usernames and passwords in your own application.

Read our Authentication docs for more detailed information regarding API Key and Basic authentication.

Rate Limiting

You can perform up to 5 request/second from the same IP address. If you exceed this limit, you'll get a 429 Too Many Requests response for subsequent requests. API usage is limited to Professional and Enterprise plans, and up to 250,000 requests per month. For increased usage please contact


These links will take you to GitHub; you can find more information on our API there.



The actions you can access in the API are dependant upon the permission levels assigned to your Image Relay account. For instance, not all users are permitted to upload files or create folders, or see a list of users. If you find yourself receiving "401 Unauthorized" errors, please confirm your permission level with your Image Relay Administrator.

If you find a typo or an error in the documentation, we welcome pull requests. You can also submit an issue (will require a github account) and we will look into it.

If you have questions or trouble implementing the API, you can reach out to and we'll help you out. Need general help with Image Relay? Check out our online support center.

Status Code Explanations

  • 401: Invalid or unauthorized API user – verify your API user is valid and authorized to access the API. Contact support if you'd like assistance.

  • 403: Missing User-Agent header - all API requests require an User-Agent header, please identify yourself appropriately

  • 405: Unknown HTTP method - we only support standard HTTP requests, please double-check your request verb

  • 429: Too many requests (throttling) – slow down your request frequency

  • 502: Under heavy load – slow down your request frequency

  • 5xx: Server error - please double-check your JSON payload for formatting errors, data integrity, etc.

Need more API Help?

Have you found a bug? Do you have an API feature request? Submit an issue (requires a github account)

You can also visit our public Slack channel for API assistance? Visit our API discussion Slack channel here (requires registration, see below)

If you haven't already created an account, you can do so via this link

Further Reading:

Image Relay API on GitHub

Creating an API Token

Did this answer your question?