v1/subscriptions
Get all subscriptions for the user or service specified in the bearer token in the authorization header. If you provide the optional entityUrn query parameter, subscriptions are filtered by that entity. Use the limit query parameter for pagination.
Returns HTTP 200 code if the operation is successful. The response body contains an array of subscriptions.
NOTE: Subscription status field is not present in the response. To retrieve the status field, use the GET /v1/subscriptions/{subscriptionId} endpoint.
Resource Information
| Method and URI | GET https://developer.api.autodesk.com/fevnt/v1/subscriptions |
| Authentication Context | user context optional |
| Required OAuth Scopes | data:read |
| Data Format | JSON |
Request
Headers
| Authorization* string | Must be Bearer <token>, where <token> is obtained via either a two-legged or three-legged OAuth flow. |
| x-request-id string | GUID used by the service team track the request |
| region string | Specifies the geographical location (region) of the server that the request is executed on. Default is US. |
| collection-id string | Specifies the collection ID being subscribed to. The request will be routed to the region containing the collection. The region header and region query parameter always have precedence over this header. |
| locale-container-id string | Specifies the Locale Service container ID. The request is routed to the region specified by this ID. The region header and region query parameter always have precedence over this header. |
Request
Query String Parameters
| entityUrn string | Entity URN used to filter which subscriptions are returned. Entity URNs are composed of a urn: prefix followed by at least three colon-separated parts, following the format: urn:namespace:type:ID
The namespace is also referred to as the Namespace Identifier (or NID). The namespace must start and end with an alphanumeric character. namespace length must be between 2 and 32 characters. namespace may contain alphanumeric, “-”, and “.” characters. All other characters are disallowed. The remainder of the URN after the namespace is considered the Namespace Specific String (NSS) and contains the type and ID fields. The NSS complies with URN RFC 8141, except that it must contain at least two colon-separated fields, “?” characters are allowed, and R, Q, and F-components are stripped and ignored. |
| cursorState string | Cursor state specified in the nextUrl from the previous response that allows you to get the next page of results. Note that the next page might be empty. |
| limit int | The maximum number of objects that can be returned. A query can return fewer than the value of limit due to filtering or other reasons. Limit must be a positive integer. If not present, limit defaults to 100 with a max of 100. |
| region string | Specifies the geographical location (region) of the server that the request is executed on. Default is US. The region header also specifies the region. If you specify both, the region header has precedence. |
| locale-container-id string | Specifies the Locale Service container ID. The request is routed to the region specified by this ID. The region header and region query parameter always have precedence over this query parameter. |
Response
HTTP Status Code Summary
| 200 OK | Successful response is a JSON object that describes pagination and subscription information. |
| 400 Bad Request | Bad Request response includes title with the general reason for the failure as well as detail containing the description of the problem. When necessary, the response can include additional error details in errors array, each element of which contains both title and detail, as well as field identifying the source of the error. |
| 401 Unauthorized | Request has not been applied because it lacks valid authentication credentials for the target resource. |
| 403 Forbidden | The server understood the request but refuses to authorize it. |
| 422 Unprocessable Entity | Server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions. |
| 429 Too Many Requests | User has sent too many requests in a given amount of time. |
| 500 Internal Server Error | An unexpected error occurred on the server. |
Response
Body Structure (200)
| pagination object | |
| limit int | The limit value used by the server in the response |
| nextUrl string | A link to the the next page of data. If null, this is the last page of data. It is allowed that a page may be empty but contain a next paging link. Consumers should stop paging when nextUrl is null.
The value returned in nextUrl should be appended to the base URL for the service to generate another request to this endpoint. |
| results array: object | |
| subscriptionId string | The ID of the subscription |
| entityUrn string | Entity URN for the subscription. Entity URNs are composed of a urn: prefix followed by at least three colon-separated parts, following the format: urn:namespace:type:ID
The namespace is also referred to as the Namespace Identifier (or NID). The namespace must start and end with an alphanumeric character. namespace length must be between 2 and 32 characters. namespace may contain alphanumeric, “-”, and “.” characters. All other characters are disallowed. The remainder of the URN after the namespace is considered the Namespace Specific String (NSS) and contains the type and ID fields. The NSS complies with URN RFC 8141, except that it must contain at least two colon-separated fields, “?” characters are allowed, and R, Q, and F-components are stripped and ignored. |
| eventType string | Event type ID for subscription. Event type IDs follow a type ID format which is composed of three sections following the format: namespace:eventType-semverVersion
An asterisk in the eventType field represents a wildcard pattern. The asterisk is used as a placeholder for zero or more characters to match other events in the namespace. For example, a eventType of asset.* would match the asset.created, asset.updated, asset.deleted, etc. event types. |
| protocol string | “WSS” (secure web sockets) or “HTTPS” (webhooks) |
| filters array: string | Array of filters (JsonPath format strings) for specific property types that must match in order for the events to be delivered (can be empty). |
| channel string | The channel name, for “WSS” protocol subscriptions. Not present for other protocols. |
| callbackUrl string | The callback URL specified when creating the subscription. This field is only present for “HTTPS” protocol subscriptions. |
| hookToken string | When using the “HTTPS” protocol, an optional parameter that represents a secret token to prevent callback spoofing. |
| created string | Subscription creation UTC time in ISO 8601 format |
| createdBy string | User ID of the person who created this subscription. For service subscriptions, this value is the same as the client ID. |
| clientId string | An ID of the app used to make the subscription |
| updated string | Last subscription modification date time (same format as created) |
| updatedBy string | User ID of the person who last modified this subscription. For service subscriptions, this value is the same as the client ID. |
| userId string | User ID of the person who created this subscription. For service subscriptions, this value is the same as the client ID. |
| subscriptionExpiry string | Optional: ISO8601 formatted date and time when the subscription should expire and automatically be deleted. null or not present means the subscription never expires. |
| status string | “active” if the subscription is active, “inactive” if the subscription is inactive, “reactivated” if the subscription was previously inactive, but has now been reactivated. Inactive subscriptions do not receive events. |
Example
Successful response is a JSON object that describes pagination and subscription information.
Request
curl -v 'https://developer.api.autodesk.com/fevnt/v1/subscriptions' \
-H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a'
Response
{
"results": [
{
"subscriptionId": "6ffaa78a-70cc-4285-8a06-70af4f50349d",
"entityUrn": "urn:autodesk.data.assetgraph:collection:co.oeq8pG2JQyO-TewgIWD3FQ",
"eventType": "autodesk.data.assetgraph:events.collection.updated-1.0.0",
"protocol": "WSS",
"filters": [],
"created": "2020-09-16T21:45:16Z",
"createdBy": "RKBNP94PYRQD",
"clientId": "zg7X5gAnLQxJrtAyGdFwtNWUZVg2PJGl",
"updated": "2020-09-16T21:45:16Z",
"updatedBy": "RKBNP94PYRQD",
"userId": "RKBNP94PYRQD",
"channel": "MYMONIKER-C-UW2-projectAlpha-b8ad2cc7-bcdb-4897-8921-99bacc35e610"
},
{
"subscriptionId": "ee39cf30-0f0c-4ec0-a7bb-b18168a5b3ab",
"entityUrn": "urn:autodesk.data.assetgraph:space:co.g5hu4wCaTcmWRSHTpuXHOQ",
"eventType": "autodesk.data.assetgraph:events.space.updated-1.0.0",
"protocol": "WSS",
"filters": [],
"created": "2020-09-16T22:15:16Z",
"createdBy": "RKBNP94PYRQD",
"clientId": "zg7X5gAnLQxJrtAyGdFwtNWUZVg2PJGl",
"updated": "2020-09-16T22:15:16Z",
"updatedBy": "RKBNP94PYRQD",
"userId": "RKBNP94PYRQD",
"subscriptionExpiry": "2021-07-15T01:15:36Z",
"channel": "MYMONIKER-C-UW2-projectAlpha-486732c8-25b2-4357-bdb3-6ff9b5ee29f5"
},
{
"subscriptionId": "9ac2fbab-9ade-4a48-93e3-bfe6db562b94",
"entityUrn": "urn:autodesk.data.assetgraph:asset:co.mVIdoF0xSBqaAJPVu8W8Bw",
"eventType": "autodesk.data.assetgraph:events.asset.updated-1.0.0",
"protocol": "WSS",
"filters": [],
"created": "2020-09-16T19:35:16Z",
"createdBy": "RKBNP94PYRQD",
"clientId": "zg7X5gAnLQxJrtAyGdFwtNWUZVg2PJGl",
"updated": "2020-09-16T19:35:16Z",
"updatedBy": "RKBNP94PYRQD",
"userId": "RKBNP94PYRQD",
"subscriptionExpiry": "2021-07-15T01:15:36Z",
"channel": "MYMONIKER-C-UW2-projectAlpha-78ab7661-1dd8-4f53-b430-db7e2cc59fee"
}
],
"pagination": {
"limit": 100,
"nextUrl": null
}
}
