The Curator REST API enables you to interact with Curator programmatically. Use this API to build apps, script interactions with Curator, or develop any other type of integration. This page documents the REST resources currently available in Curator API, including the HTTP response codes and example requests and responses.
\r\nOpenAPI Specification is an API description format for REST APIs. Curator REST API conforms to OpenAPI 3.0 Specification.
\r\nCurator REST OpenAPI specification can be downloaded using the link above and imported into tools such as Postman for testing or Swagger Codegen for SDK code generation.
\r\nAll API access is accessed from https://[host]/CuratorGateway/api/v1. All data is sent and received as JSON.
\r\nBlank fields are included as null instead of being omitted.
All timestamps return in ISO 8601 format and are UTC without timezone information:
\r\nYYYY-MM-DDTHH:MM:SSZ
This documentation is for version 1 of the Curator REST API, which is the latest version.
\r\nThe URIs for resources have the following structure:
\r\nhttps://[host]/CuratorGateway/api/v1/
For example, https://[host]/CuratorGateway/api/v1/assets/00000000000000000000000001162429
You can issue a GET request to the root endpoint to get all the endpoint categories that the Curator REST API v1 supports:
https://[host]/CuratorGateway/api/v1
All resources may have one or more href properties linking to other resources. These are meant to provide explicit URLs so that proper API clients don't need to construct URLs on their own. It is highly recommended that API clients use these. Doing so will make future upgrades of the API easier for developers. All URLs are expected to be proper RFC 6570 URI templates.
Such as:
\r\n\r\n
\r\n{\r\n\t\"href\": \"https://[host]/CuratorGateway/api/v1/assets/5be52a09-e43f-4a48-b41b-5c33b95ee53a/metadata/MyMetadataName\",\r\n\t\"displayName\": \"My Metadata Name\",\r\n\t\"values\": [\r\n\t\t\"My Metadata Value\"\r\n\t],\r\n\t\"type\": \"Text\",\r\n\t\"name\": {\r\n\t\t\"href\": \"https://[host]/CuratorGateway/api/v1/metadatanames/MyMetadataName\"\r\n\t}\r\n}\r\n\r\n\r\nThe Curator REST API uses the standard HTTP status codes.
\r\nOperations that return an error status code may also return a response body containing details of the error or errors. The schema for each response code can be found under each API request.
\r\nWhen interaction with the Curator API, your application will access Curator on behalf of your users.
\r\nCurator API uses OAuth 2.0, an open specification, to authorise access to a user's data and Curator API resources. The primary goal of OAuth is to allow developers to interact with Curator API without requiring them to store sensitive credentials.
\r\nCurator API supports common OAuth 2.0 scenarios such as those for web server, client-side, installed, and limited-input device applications.
\r\nOnce complete, the OAuth flow returns an access token to your client application. This access token should be added to all Curator API requests in the Authorization HTTP header in this format Bearer [access token].
In order for your application to request an access token on behalf of a user, you must first register it with Curator. This can be done via the Curator Gateway admin console (Authentication -> Clients).
\r\nOnce you have registered your client application you will be issued a client_id.
When you add your client application you will be asked which API Resources scopes that you client application needs access to. The selected scopes are applied to your access token and determine which API calls your application is allowed to execute. Each Curator API request below documents which API Resoure scopes are required.
\r\nBelow is a list of example API resource scopes:
\r\nCurator.Server.APICurator.Gateway.APICurator.ProcessEngine.APISee the Authentication section below for a complete list of supported API resource scopes.
\r\nIn OAuth 2.0, the term “grant type” refers to the way an application gets an access token. OAuth 2.0 defines several grant types which Curator supports.
\r\n
The Authorization Code is the recommended OAuth grant type for all applications. When you register your client application you can specifiy the supported grant types.
\r\nAt a high level, the Authorisation Code flow has the following steps:
\r\nauthorize endpoint.token endpoint.To request an access token using the authorisation code grant type.
\r\n1. Make a GET request to the authorize endpoint.
https://[host]/CuratorGateway/connect/authorize?client_id=0a677a41c5f7491d949c9eb4b1098ab0&redirect_uri=https://myapp.com&response_type=code&grant_type=authorization_code&scope=Curator.Server.API Curator.Gateway.API\r\n
response_type=code - This tells the Curator that the application is initiating the authorisation code flow.client_id - Your client application id.redirect_uri - Tells the Curator where to send the user back to after they approve the request.scope - One or more space-separated strings indicating which permissions the application is requesting. See the authentication section below for a complete list of API resource scopes.2. The user will then be redirected to the Curator login screen and asked if they would like to authorise your client application.
\r\n3. If the user approves the authorisation request, Curator will redirect back to the redirect_uri specified in step 1., adding code to the query string.
https://myapp.com?code=CDD37395D64516E883615AD8862862585A5765C07E890E1022B708A43C2C04F7\r\n
4. The code can now be exchanged for an access token using the token endpoint.
The client application makes a POST request to the Curator's token endpoint with the following parameters:
\r\ngrant_type=authorization_code - This tells the Curator that the application is using the authorisation code flow.code - The application includes the authorisation code it was given in the redirect.redirect_uri - The same redirect URI that was used when requesting the code.client_id - The application’s client ID.client_secret - The application’s client secret. This should be the same as the client_id.The response will include the access_token which can then be used to make Curator API requests.
\r\n{\r\n \"access_token\": \"A52CF2278F7749B914102FA39C8D6A1834C676EBA2D86AE7710A816FDA9E4D11\",\r\n \"expires_in\": 3600,\r\n \"token_type\": \"Bearer\",\r\n \"scope\": \"Curator.Server.API Curator.Gateway.API\"\r\n}\r\n\r\nCan I use the simpler 'resource owner password' grant type?
\r\n\r\n The 'OAuth 2.0 Security Best Current Practice' disallows the password grant entirely. This\r\n grant type insecurely exposes the credentials of the user\r\n to the client. Even if the client is benign, this results in an\r\n increased attack surface (credentials can leak in more places than\r\n just the Curator Gateway) and users are trained to enter their credentials in\r\n places other than the Curator Gateway.\r\n Also, features such as multi-factor authentication, single sign-on and federation are not possible.\r\n
\r\nWhat about the 'client credentials' server-to-server grant type?
\r\n\r\n All Curator API requests require a users identity to be included in the access token\r\n so that Curator can evaluate the acting users permissions. The process for obtaining access tokens on-behalf of a user\r\n is described above. Although supported by Curator Gateway, grant types like 'client credentials' should not be used.\r\n
\r\nThe Curartor REST API uses pagination to improve performance. Pagination is enforced for operations that could return a large collection of resources.
\r\nWhen a request is made for paged resources, offset and limit query string parameters can be used to define the position and size of the resultset, such as:
https://[host]/CuratorGateway/api/v1/users?offset=5&limit=10\r\nWhen you make a request to a paginated resource, the response wraps the returned array of values in a JSON object with paging metadata.
\r\noffset - The offset into the list of items.limit - The limit/size of items requested.size - The total number of resources.next - The link relation for the immediate next page of results.last - The link relation for the last page of results.first - The link relation for the first page of results.previous - The link relation for the immediate previous page of results.\r\n{\r\n \"href\": \"https://[host]/CuratorGateway/api/v1/users?offset=5&limit=10\",\r\n \"rel\": [\r\n \"collection\"\r\n ],\r\n \"offset\": 5,\r\n \"limit\": 10,\r\n \"size\": 23,\r\n \"first\": {\r\n \"href\": \"https://[host]/CuratorGateway/api/v1/users?offset=5&limit=10\",\r\n \"rel\": [\r\n \"collection\"\r\n ]\r\n },\r\n \"previous\": {\r\n \"href\": \"https://[host]/CuratorGateway/api/v1/users?offset=5&limit=10\",\r\n \"rel\": [\r\n \"collection\"\r\n ]\r\n },\r\n \"next\": {\r\n \"href\": \"https://[host]/CuratorGateway/api/v1/users?offset=15&limit=10\",\r\n \"rel\": [\r\n \"collection\"\r\n ]\r\n },\r\n \"last\": {\r\n \"href\": \"https://[host]/CuratorGateway/api/v1/users?offset=20&limit=10\",\r\n \"rel\": [\r\n \"collection\"\r\n ]\r\n },\r\n \"value\": [\r\n\t...\r\n ]\r\n}\r\n\r\nSome Curator REST API operations may trigger long-running or computationally expensive tasks. In these cases, the operation will schedule an asynchronous task and return a 302 response, indicating the location of the queued task in the Location header. You can query the task by making requests to Get Task for progress updates.
When the task finishes, the response object will contain the results field. The content of the field is specific to the operation that created the task.
Note that asynchronous tasks are not guaranteed to be run in order. In other words, if you need your tasks to execute in a certain order, you should start a task only after the prerequisite task(s) have finished.
\r\nIf further information is required, please contact us via our Support Portal or visit the Documentation Hub.
\n\nContact Support:\n Name: IPV\n Email: support@ipv.com","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"2965282","collectionId":"fe4a90dd-70f1-4a59-b0ff-50878c83d055","publishedId":"TVKD1xGG","public":true,"publicUrl":"https://documenter-api.postman.tech/view/2965282/TVKD1xGG","privateUrl":"https://go.postman.co/documentation/2965282-fe4a90dd-70f1-4a59-b0ff-50878c83d055","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"303030"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.10.1","publishDate":"2020-09-21T15:18:29.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/768118b36f06c94b0306958b980558e6915839447e859fe16906e29d683976f0","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/TVKD1xGG"}