# Marketplace
# Marketplace
The product catalogue and provisioning service: bundles, versioned publication, dependency resolution and single-call rollback.
Publishing makes a bundle installable. The catalogue resolves what a bundle depends on, installs the set, and keeps every published version so a rollback is one call rather than a redeployment.
It also serves the ontology itself. Families, categories, products, APIs and prices are readable and writable through it, so the product tree is queryable rather than only written down.
## How it works
Every publication is proved twice before it ships. A bundle and its dependencies are installed into a long-lived review environment, which proves it can go into an environment that already has state, and into a second environment wiped daily, which proves it can install from nothing. A bundle that cannot do both does not publish.
Those are different failure modes. An installer that assumes prior state breaks on a new customer; an installer that assumes a clean slate breaks on an upgrade. Testing only one of them catches half the class.
## Operations
### Athlete
`POST` `/ontology/athletes`
#### Register Athlete
`register_athlete`
This endpoint registers an `Athlete` entity in the ontology, allowing for future links of such to the `Team` entity.
##### Request
application/json Copy
```
{
"first_name": "Sebastian",
"last_name": "Vettel",
"email": "sebastian.vettel@gmail.com"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `first_name`required | `string` | Athlete's name |
| `last_name`required | `string` | Athlete's surname |
| `email`required | `string` | Email address of the Athlete |
##### Response `201``application/json`
1 fields
Athlete has been registered.
| Field | Type | Description |
| --- | --- | --- |
| `athlete_id` | `string` | Athlete ID referencing the registered Athlete. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`DELETE` `/ontology/athletes/{athlete_id}`
#### Delete Athlete
`delete_athlete`
This endpoint deletes `Athlete` from the ontology.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `athlete_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Athlete ID |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
`GET` `/ontology/athletes/{athlete_id}`
#### Retrieve Athlete
`retrieve_athlete`
This endpoint retrieves `Athlete` from the ontology. User can additionally request for the team information to which athlete is linked to be returned using the query parameters.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `athlete_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Athlete ID |
| `include_team_info` | `boolean` query | `true` | Switch for the team information |
##### Response `200``application/json`
1 fields
Athlete has been retrieved.
| Field | Type | Description |
| --- | --- | --- |
| `athlete` | `object` | Athlete information |
| `athlete_id`required | `string` | Athlete ID referencing the registered Athlete. |
| `first_name`required | `string` | First name of the Athlete |
| `last_name`required | `string` | Last name of the Athlete |
| `email`required | `string` | Email address of the Athlete |
| `team` | `object` | Team information |
| `team_name`required | `string` | Team name |
| `team_id`required | `string` | Team ID |
| `created_at`required | `string` | Date of the creation |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`PATCH` `/ontology/athletes/{athlete_id}`
#### Update Athlete
`update_athlete`
This endpoint updates `Athlete` instance in the ontology.
##### Request
application/json Copy
```
{
"first_name": "Sebastian"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `athlete_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Athlete ID |
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `first_name` | `string` | Athlete's first name |
| `last_name` | `string` | Athlete's last name |
| `email` | `string` | Athlete's email address |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
### Team
`POST` `/ontology/teams`
#### Register Team
`register_team`
This endpoint registers a `Team` entity in the ontology, allowing for future references of such in relation to `Athlete` and `Product` entities.
##### Request
application/json Copy
```
{
"team_name": "Bohr"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `team_name`required | `string` | Team name |
##### Response `201``application/json`
1 fields
Team has been registered.
| Field | Type | Description |
| --- | --- | --- |
| `team_id` | `string` | Team ID referencing the registered Team. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`GET` `/ontology/teams`
#### Retrieve Teams
`retrieve_teams`
This endpoint retrieves all registered Teams in the ontology.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Response `200``application/json`
1 fields
Team has been registered.
| Field | Type | Description |
| --- | --- | --- |
| `teams` | `array` | Array of retrieved Teams |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`DELETE` `/ontology/teams/{team_id}`
#### Delete Team
`delete_team`
This endpoint deletes `Team` from the ontology.
#### Warning
If the referenced `Team` has `Athlete` or `Product` linked to it, user should first unlink those and only then proceed with the deletion.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `team_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Team ID |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
`PATCH` `/ontology/teams/{team_id}`
#### Update Team
`update_team`
This endpoint updates `Team` instance in the ontology.
##### Request
application/json Copy
```
{
"team_name": "Bushnell"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `team_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Team ID |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `team_name`required | `string` | Team name |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
`GET` `/ontology/teams/{team_id}`
#### Retrieve Team
`retrieve_team`
This endpoint retrieves `Team` from the ontology.
#### Query Parameters
User can specify whether the information about the Team's linked products or athletes is needed, which is `false` by default.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `team_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Team ID |
| `include_athletes_info` | `boolean` query | `true` | Switch for the athlete information |
| `include_products_info` | `boolean` query | `true` | Switch for the product information |
##### Response `200``application/json`
1 fields
Athlete has been retrieved.
| Field | Type | Description |
| --- | --- | --- |
| `team`required | `object` | Team information |
| `team_name`required | `string` | Team name |
| `team_id`required | `string` | Team ID |
| `created_at`required | `string` | Date of the creation |
| `products` | `array` | Array of products linked to the Team |
| `athletes` | `array` | Array of athletes linked to the Team |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`POST` `/ontology/teams/{team_id}/athletes`
#### Link Athlete to Team
`link_athlete_to_team`
This endpoint links the specified `Athlete` to the provided `Team`. If the `Athlete` is already linked with some `Team`, the request is declined - user should unlink it from that `Team` first.
##### Request
application/json Copy
```
{
"athlete_id": "436bffb6-f398-469b-b619-55f0ecf09b65"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `team_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Team ID |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `athlete_id`required | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
##### Response `201``application/json`
1 fields
Athlete has been successfully linked to the Team.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Success message |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`DELETE` `/ontology/teams/{team_id}/athletes/{athlete_id}`
#### Unlink Athlete from Team
`unlink_athlete_from_team`
This endpoint unlinks `Athlete` from the provided `Team`. If the provided 'Athlete' is not linked with the given `Team` the request is declined.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `team_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Team ID |
| `athlete_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Athlete ID |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
`POST` `/ontology/teams/{team_id}/products`
#### Link Product to Team
`link_product_to_team`
This endpoint links the specified `Product` to the provided `Team`. If the `Product` is already linked with some `Team`, the request is declined - user should unlink it from that `Team` first.
##### Request
application/json Copy
```
{
"product_id": "c5b605e0-54bf-45a1-b275-400e3313be9c"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `team_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Team ID |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `product_id`required | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
##### Response `201``application/json`
1 fields
Product has been successfully linked to the Team.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Success message |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`DELETE` `/ontology/teams/{team_id}/products/{product_id}`
#### Unlink Product from Team
`unlink_product_from_team`
This endpoint unlinks `Product` from the provided `Team`. If the provided 'Product' is not linked with the given `Team` the request is declined.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `team_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Team ID |
| `product_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Product ID |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
### Subscription[warning]
`POST` `/subscriptions`
#### Create Subscription[warning]
`createSubscription`
Create a subscription
Create a subscription for components to keep an environment up to date.
If a component contains dependencies, all dependencies will be added to subscription automatically. After a subscription is created or updated, all new items will be deployed immediately. Response contains the list of subscribed to products including dependencies.
##### Subscribing using product identifiers
Retrieve components, that are linked to a particular product, use `Get Product Components` endpoint.
Show the rest Example in python:
```
import requests
http = requests.Session
http.headers['x-api-key'] = marketplace_api_key
def get_components(marketplace_env: str, product_id: str) -> list[str]:
response = http.get(f"")
return response.json['components']
component_names = [
*get_components(marketplace_domain_name, product_id_of_connector),
*get_components(marketplace_domain_name, product_id_of_persistence),
]
http.post(
"",
json={
"domain_name": subscriber_domain_name,
"api_key": subscriber_api_key,
"component_names": component_names,
},
)
```
You can read more about linking a component to a product `here`
##### Subscription status
Status changes when subscription-specific operations occur. For example, if the Component to which you're subscribed gets an update, or you create a subscription. The following is an ordered flow for the subscription status changes.
| Status | Meaning |
| --- | --- |
| `INITIATED` | Subscription to a component has been created and awaiting the delivery. |
| `IN_QUEUE` | Delivery started, deployments are pending. |
| `FAILED` | Delivery failed, deployment attempts have failed. |
| `SUCCEEDED` | Delivery succeeded. |
##### Observe delivery status
One way of observing deliveries' statuses in your environment is using `Listen to Deliveries` API. However, if you don't need to monitor deliveries continuously – you can tell Marketplace to notify you once the component you initiated a direct subscription to has or hasn't been successfully delivered. The notification is emitted via the “webhook” with a structure of its payload described below.
Delivery statuses of dependencies are included only if there were failed deliveries
Events are sent in payloads of a “HTTP requests” using `POST` method.
```
{
"$schema": "",
"additionalProperties": true,
"type": "object",
"description": "Schema for the payload event emitted to callback.",
"properties": {
"transaction_id": {
"type": "string",
"description": "Transaction identifier. Unique per delivery."
},
"truncated": {
"type": "boolean",
"description": "Event can be truncated if many direct subscriptions were initiated."
},
"domain_name": {
"type": "string",
"description": "Subscription receiver domain name."
},
"components": {
"type": "array",
"description": "List of components subscription was initiated for.",
"items": {
"type": "object",
"properties": {
"component_name": {
"type": "string",
"description": "Component name delivery initiated for."
},
"last_deployment_id": {
"type": "string",
"description": "Latest available deployment ID used in delivery. Can be null."
},
"delivery_status": {
"type": "string",
"enum": [
"FAILED",
"SUCCEEDED"
],
"description": "The status of the delivery."
},
"component_publication_id": {
"type": "string",
"description": "The bundle ID of a component used in the delivery process. Can be null."
},
"status_updated_date": {
"type": "string",
"description": "Last time the status was updated."
}
}
}
},
"failed_dependencies": {
"type": "array",
"description": "List of components subscription was initiated for.",
"items": {
"type": "object",
"properties": {
"component_name": {
"type": "string",
"description": "Component name delivery initiated for."
},
"last_deployment_id": {
"type": "string",
"description": "Latest available deployment ID used in delivery. Can be null."
},
"delivery_status": {
"type": "string",
"enum": [
"FAILED",
"SUCCEEDED"
],
"description": "The status of the delivery."
},
"component_publication_id": {
"type": "string",
"description": "The bundle ID of a component used in the delivery process. Can be null."
},
"status_updated_date": {
"type": "string",
"description": "Last time the status was updated."
}
}
}
}
}
}
```
###### Troubleshooting
Events are dispatched once the delivery process completes, which includes the successful or failed deployment of all components and their respective dependencies.
An event is deemed as successfully delivered when its recipient acknowledges with an HTTP status code that falls within the range of successful responses. If an event isn't successfully delivered, the Marketplace will make six additional attempts to resend the event, with each attempt following an exponential back off strategy.
To confirm the propagation of the webhook, you can utilize Retrieve Transaction Collections with the transaction ID, which is returned during the creation of the subscription.
Collection data example:
```
{
"delivery": {
"components": [
{
"status_updated_date": "2023-05-05T12:28:38.547030+00:00",
"component_name": "Marketplace",
"delivery_status": "SUCCEEDED",
"component_publication_id": "01H01965DB8QGSD9EZWF1VS7BC"
},
{
"status_updated_date": "2023-05-05T12:28:38.547030+00:00",
"component_name": "marketplace-ontology",
"delivery_status": "SUCCEEDED",
"component_publication_id": "01G02003BD8GQSD9ZEFF1BEVND"
}
],
"domain_name": "tea.staircaseapi.com",
"failed_dependencies": [],
"truncated": false
},
"partner_response": {
"request_response_elapsed_time": 0.38052,
"response_status_code": 200,
"response_text": "{\"message\": \"event_received\"}",
"http_connection_established": true
}
}
```
Collection is not yet valid for the Lexicon version 3.
#### Deprecation notice
Marketplace will stop accepting `products` and `data` fields starting from December 2022. In order to subscribe to components, please use `component_names` field instead.
Example:
```
import requests
requests.post(
"",
json={
"domain_name": subscriber_domain_name,
"api_key": subscriber_api_key,
"component_names": [
"Connector",
"Deploy",
"Health",
],
},
)
```
#### Open endpoint
This endpoint is open. Endpoint is open, when you can omit request authorization via `x-api-key` header.
#### Subscriber validation
Marketplace will validate `domain_name` to `api_key` attachment to verify the claim of the environment ownership. Depending on the ownership validation results, Marketplace can either abort or the request or carry on with the subscription changes.
##### Request
Subscribe to Miscellaneous ComponentsSubscribe to Credit ComponentsSubscribe to DevOps Suite Components
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "one.staircaseapi.com",
"component_names": [
"Deploy",
"Environment"
]
}
```
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "amazing.staircaseapi.com",
"components_names": [
"Credit"
]
}
```
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "one.staircaseapi.com",
"component_names": [
"Assess",
"Assess-security-data",
"Assess-staircase-data",
"Assess-swagger-data",
"Build",
"Code",
"Comply",
"Deploy",
"Environment",
"Test"
]
}
```
##### Response
201400 application/json400 text/html403404409
application/json Copy Subscription has been created
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "one.staircaseapi.com",
"component_names": [
"Assess",
"Assess-security-data",
"Assess-staircase-data",
"Assess-swagger-data",
"Build",
"Code",
"Comply",
"Deploy",
"Environment",
"Test"
]
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested product not found
```
{
"message": "Component was not found"
}
```
application/json Copy Subscription already exist
```
{
"message": "Subscription for domain already exists"
}
```
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `domain_name`required | `string` | Environment domain nameExample `template.staircaseapi.com` |
| `api_key`required | `string` | Environment API keyExample `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
| `component_names`required | `string[]` | Array of component names. Must have unique items. |
| `callback_url` | `string (uri)` | Used for a subscription observability. |
##### Response `201``application/json`
2 fields
Subscription has been created
| Field | Type | Description |
| --- | --- | --- |
| `domain_name` | `string` | Environment domain nameExample `template.staircaseapi.com` |
| `component_names` | `string[]` | The list of components to subscribe to |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested product not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error message.Example `Component was not found` |
##### Response `409``application/json`
1 fields
Subscription already exist
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Conflict error message.Example `Subscription for domain already exists` |
`PATCH` `/subscriptions`
#### Extend Subscription[warning]
`updateSubscription`
Extend a subscription.
Extend a subscription for components to keep environment up to date.
This operation will extend existing subscriptions, keeping them together with new ones.
If a component contains dependencies, all dependencies will be added to the subscription automatically. After subscription is created or updated, all new items will be deployed immediately. Response contains the list of new subscribed to products including dependencies.
Show the rest
##### Subscribing using product identifiers
Retrieve components, that are linked to a particular product, use `Get Product Components` endpoint.
Example in python:
```
import requests
http = requests.Session
http.headers['x-api-key'] = marketplace_api_key
def get_components(marketplace_env: str, product_id: str) -> list[str]:
response = http.get(f"")
return response.json['components']
component_names = [
*get_components(marketplace_domain_name, product_id_of_connector),
*get_components(marketplace_domain_name, product_id_of_persistence),
]
http.post(
"",
json={
"domain_name": subscriber_domain_name,
"api_key": subscriber_api_key,
"component_names": component_names,
},
)
```
You can read more about linking a component to a product `here`
##### Subscription status
Status changes when subscription-specific operations occur. For example, if the Component to which you're subscribed gets an update, or you create a subscription. The following is an ordered flow for the subscription status changes.
| Status | Meaning |
| --- | --- |
| `INITIATED` | Subscription to a component has been created and awaiting the delivery. |
| `IN_QUEUE` | Delivery started, deployments are pending. |
| `FAILED` | Delivery failed, deployment attempts have failed. |
| `SUCCEEDED` | Delivery succeeded. |
##### Observe delivery status
One way of observing deliveries' statuses in your environment is using `Listen to Deliveries` API. However, if you don't need to monitor deliveries continuously – you can tell Marketplace to notify you once the component you initiated a direct subscription to has or hasn't been successfully delivered. The notification is emitted via the “webhook” with a structure of its payload described below.
Delivery statuses of dependencies are included only if there were failed deliveries
Events are sent in payloads of a “HTTP requests” using `POST` method.
```
{
"$schema": "",
"additionalProperties": true,
"type": "object",
"description": "Schema for the payload event emitted to callback.",
"properties": {
"transaction_id": {
"type": "string",
"description": "Transaction identifier. Unique per delivery."
},
"truncated": {
"type": "boolean",
"description": "Event can be truncated if many direct subscriptions were initiated."
},
"domain_name": {
"type": "string",
"description": "Subscription receiver domain name."
},
"components": {
"type": "array",
"description": "List of components subscription was initiated for.",
"items": {
"type": "object",
"properties": {
"component_name": {
"type": "string",
"description": "Component name delivery initiated for."
},
"last_deployment_id": {
"type": "string",
"description": "Latest available deployment ID used in delivery. Can be null."
},
"delivery_status": {
"type": "string",
"enum": [
"FAILED",
"SUCCEEDED"
],
"description": "The status of the delivery."
},
"component_publication_id": {
"type": "string",
"description": "The bundle ID of a component used in the delivery process. Can be null."
},
"status_updated_date": {
"type": "string",
"description": "Last time the status was updated."
}
}
}
},
"failed_dependencies": {
"type": "array",
"description": "List of components subscription was initiated for.",
"items": {
"type": "object",
"properties": {
"component_name": {
"type": "string",
"description": "Component name delivery initiated for."
},
"last_deployment_id": {
"type": "string",
"description": "Latest available deployment ID used in delivery. Can be null."
},
"delivery_status": {
"type": "string",
"enum": [
"FAILED",
"SUCCEEDED"
],
"description": "The status of the delivery."
},
"component_publication_id": {
"type": "string",
"description": "The bundle ID of a component used in the delivery process. Can be null."
},
"status_updated_date": {
"type": "string",
"description": "Last time the status was updated."
}
}
}
}
}
}
```
###### Troubleshooting
Events are dispatched once the delivery process completes, which includes the successful or failed deployment of all components and their respective dependencies.
An event is deemed as successfully delivered when its recipient acknowledges with an HTTP status code that falls within the range of successful responses. If an event isn't successfully delivered, the Marketplace will make six additional attempts to resend the event, with each attempt following an exponential back off strategy.
To confirm the propagation of the webhook, you can utilize Retrieve Transaction Collections with the transaction ID, which is returned during the creation of the subscription.
Collection data example:
```
{
"delivery": {
"components": [
{
"status_updated_date": "2023-05-05T12:28:38.547030+00:00",
"component_name": "Marketplace",
"delivery_status": "SUCCEEDED",
"component_publication_id": "01H01965DB8QGSD9EZWF1VS7BC"
},
{
"status_updated_date": "2023-05-05T12:28:38.547030+00:00",
"component_name": "marketplace-ontology",
"delivery_status": "SUCCEEDED",
"component_publication_id": "01G02003BD8GQSD9ZEFF1BEVND"
}
],
"domain_name": "tea.staircaseapi.com",
"failed_dependencies": [],
"truncated": false
},
"partner_response": {
"request_response_elapsed_time": 0.38052,
"response_status_code": 200,
"response_text": "{\"message\": \"event_received\"}",
"http_connection_established": true
}
}
```
Collection is not yet valid for the Lexicon version 3.
#### Deprecation notice
Marketplace will stop accepting `products` and `data` fields starting from December 2022. In order to subscribe to components, please use `component_names` field instead.
Example:
```
import requests
requests.patch(
"",
json={
"domain_name": subscriber_domain_name,
"api_key": subscriber_api_key,
"component_names": [
"Connector",
"Deploy",
"Health",
],
},
)
```
#### Open endpoint
This endpoint is open. Endpoint is open, when you can omit request authorization via `x-api-key` header.
#### Subscriber validation
Marketplace will validate `domain_name` to `api_key` attachment to verify the claim of the environment ownership. Depending on the ownership validation results, Marketplace can either abort or the request or carry on with the subscription changes.
##### Request
Subscribe to Miscellaneous ComponentsSubscribe to Credit ComponentsSubscribe to DevOps Suite Components
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "one.staircaseapi.com",
"component_names": [
"Deploy",
"Environment"
]
}
```
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "amazing.staircaseapi.com",
"components_names": [
"Credit"
]
}
```
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "one.staircaseapi.com",
"component_names": [
"Assess",
"Assess-security-data",
"Assess-staircase-data",
"Assess-swagger-data",
"Build",
"Code",
"Comply",
"Deploy",
"Environment",
"Test"
]
}
```
##### Response
201400 application/json400 text/html403404
application/json Copy Subscription has been updated
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "one.staircaseapi.com",
"component_names": [
"Assess",
"Assess-security-data",
"Assess-staircase-data",
"Assess-swagger-data",
"Build",
"Code",
"Comply",
"Deploy",
"Environment",
"Test"
]
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested subscription not found
```
{
"message": "Subcription not found"
}
```
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `domain_name`required | `string` | Environment domain nameExample `template.staircaseapi.com` |
| `api_key`required | `string` | Environment API keyExample `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
| `component_names`required | `string[]` | Array of component names. Must have unique items. |
| `callback_url` | `string (uri)` | Used for a subscription observability. |
##### Response `201``application/json`
2 fields
Subscription has been updated
| Field | Type | Description |
| --- | --- | --- |
| `domain_name` | `string` | Environment domain nameExample `template.staircaseapi.com` |
| `component_names` | `string[]` | The list of components to subscribe to |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested subscription not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error message.Example `Subcription not found` |
`PUT` `/subscriptions`
#### Modify Subscription[warning]
`modifySubscription`
Modify subscription.
Modifies subscription for components to keep environment up to date.
This operation will overwrite existing subscriptions.
If a component contains dependencies, all dependencies will be added to the subscription automatically. After subscription is created or updated, all new items will be deployed immediately. Response contains the list of new subscribed to products including dependencies.
Show the rest
##### Subscribing using product identifiers
Retrieve components, that are linked to a particular product, use `Get Product Components` endpoint.
Example in python:
```
import requests
http = requests.Session
http.headers['x-api-key'] = marketplace_api_key
def get_components(marketplace_env: str, product_id: str) -> list[str]:
response = http.get(f"")
return response.json['components']
component_names = [
*get_components(marketplace_domain_name, product_id_of_connector),
*get_components(marketplace_domain_name, product_id_of_persistence),
]
http.post(
"",
json={
"domain_name": subscriber_domain_name,
"api_key": subscriber_api_key,
"component_names": component_names,
},
)
```
You can read more about linking a component to a product `here`
##### Subscription status
Status changes when subscription-specific operations occur. For example, if the Component to which you're subscribed gets an update, or you create a subscription. The following is an ordered flow for the subscription status changes.
| Status | Meaning |
| --- | --- |
| `INITIATED` | Subscription to a component has been created and awaiting the delivery. |
| `IN_QUEUE` | Delivery started, deployments are pending. |
| `FAILED` | Delivery failed, deployment attempts have failed. |
| `SUCCEEDED` | Delivery succeeded. |
##### Observe delivery status
One way of observing deliveries' statuses in your environment is using `Listen to Deliveries` API. However, if you don't need to monitor deliveries continuously – you can tell Marketplace to notify you once the component you initiated a direct subscription to has or hasn't been successfully delivered. The notification is emitted via the “webhook” with a structure of its payload described below.
Delivery statuses of dependencies are included only if there were failed deliveries
Events are sent in payloads of a “HTTP requests” using `POST` method.
```
{
"$schema": "",
"additionalProperties": true,
"type": "object",
"description": "Schema for the payload event emitted to callback.",
"properties": {
"transaction_id": {
"type": "string",
"description": "Transaction identifier. Unique per delivery."
},
"truncated": {
"type": "boolean",
"description": "Event can be truncated if many direct subscriptions were initiated."
},
"domain_name": {
"type": "string",
"description": "Subscription receiver domain name."
},
"components": {
"type": "array",
"description": "List of components subscription was initiated for.",
"items": {
"type": "object",
"properties": {
"component_name": {
"type": "string",
"description": "Component name delivery initiated for."
},
"last_deployment_id": {
"type": "string",
"description": "Latest available deployment ID used in delivery. Can be null."
},
"delivery_status": {
"type": "string",
"enum": [
"FAILED",
"SUCCEEDED"
],
"description": "The status of the delivery."
},
"component_publication_id": {
"type": "string",
"description": "The bundle ID of a component used in the delivery process. Can be null."
},
"status_updated_date": {
"type": "string",
"description": "Last time the status was updated."
}
}
}
},
"failed_dependencies": {
"type": "array",
"description": "List of components subscription was initiated for.",
"items": {
"type": "object",
"properties": {
"component_name": {
"type": "string",
"description": "Component name delivery initiated for."
},
"last_deployment_id": {
"type": "string",
"description": "Latest available deployment ID used in delivery. Can be null."
},
"delivery_status": {
"type": "string",
"enum": [
"FAILED",
"SUCCEEDED"
],
"description": "The status of the delivery."
},
"component_publication_id": {
"type": "string",
"description": "The bundle ID of a component used in the delivery process. Can be null."
},
"status_updated_date": {
"type": "string",
"description": "Last time the status was updated."
}
}
}
}
}
}
```
###### Troubleshooting
Events are dispatched once the delivery process completes, which includes the successful or failed deployment of all components and their respective dependencies.
An event is deemed as successfully delivered when its recipient acknowledges with an HTTP status code that falls within the range of successful responses. If an event isn't successfully delivered, the Marketplace will make six additional attempts to resend the event, with each attempt following an exponential back off strategy.
To confirm the propagation of the webhook, you can utilize Retrieve Transaction Collections with the transaction ID, which is returned during the creation of the subscription.
Collection data example:
```
{
"delivery": {
"components": [
{
"status_updated_date": "2023-05-05T12:28:38.547030+00:00",
"component_name": "Marketplace",
"delivery_status": "SUCCEEDED",
"component_publication_id": "01H01965DB8QGSD9EZWF1VS7BC"
},
{
"status_updated_date": "2023-05-05T12:28:38.547030+00:00",
"component_name": "marketplace-ontology",
"delivery_status": "SUCCEEDED",
"component_publication_id": "01G02003BD8GQSD9ZEFF1BEVND"
}
],
"domain_name": "tea.staircaseapi.com",
"failed_dependencies": [],
"truncated": false
},
"partner_response": {
"request_response_elapsed_time": 0.38052,
"response_status_code": 200,
"response_text": "{\"message\": \"event_received\"}",
"http_connection_established": true
}
}
```
Collection is not yet valid for the Lexicon version 3.
#### Deprecation notice
Marketplace will stop accepting `products` and `data` fields starting from December 2022. In order to subscribe to components, please use `component_names` field instead.
Example:
```
import requests
requests.put(
"",
json={
"domain_name": subscriber_domain_name,
"api_key": subscriber_api_key,
"component_names": [
"Connector",
"Deploy",
"Health",
],
},
)
```
#### Open endpoint
This endpoint is open. Endpoint is open, when you can omit request authorization via `x-api-key` header.
#### Subscriber validation
Marketplace will validate `domain_name` to `api_key` attachment to verify the claim of the environment ownership. Depending on the ownership validation results, Marketplace can either abort or the request or carry on with the subscription changes.
##### Request
Subscribe to Miscellaneous ComponentsSubscribe to Credit ComponentsSubscribe to DevOps Suite Components
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "one.staircaseapi.com",
"component_names": [
"Deploy",
"Environment"
]
}
```
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "amazing.staircaseapi.com",
"components_names": [
"Credit"
]
}
```
application/json Copy
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "one.staircaseapi.com",
"component_names": [
"Assess",
"Assess-security-data",
"Assess-staircase-data",
"Assess-swagger-data",
"Build",
"Code",
"Comply",
"Deploy",
"Environment",
"Test"
]
}
```
##### Response
201400 application/json400 text/html403404
application/json Copy Subscription has been updated
```
{
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"domain_name": "one.staircaseapi.com",
"component_names": [
"Assess",
"Assess-security-data",
"Assess-staircase-data",
"Assess-swagger-data",
"Build",
"Code",
"Comply",
"Deploy",
"Environment",
"Test"
]
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested subscription not found
```
{
"message": "Subcription not found"
}
```
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `domain_name`required | `string` | Environment domain nameExample `template.staircaseapi.com` |
| `api_key`required | `string` | Environment API keyExample `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
| `component_names`required | `string[]` | Array of component names. Must have unique items. |
| `callback_url` | `string (uri)` | Used for a subscription observability. |
##### Response `201``application/json`
2 fields
Subscription has been updated
| Field | Type | Description |
| --- | --- | --- |
| `domain_name` | `string` | Environment domain nameExample `template.staircaseapi.com` |
| `component_names` | `string[]` | The list of components to subscribe to |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested subscription not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error message.Example `Subcription not found` |
`DELETE` `/subscriptions/{domain_name}`
#### Delete Subscription[warning]
`deleteSubscription`
Delete a subscription
Delete subscription from an environment.
If query parameter not specified then a subscription for all components will be deleted.
This will delete deployment history for affected components.
#### Deprecation notice
Marketplace will stop accepting `product_name` and `data_bundle_name` query parameters starting from December 2022. In order to delete subscription from a component, please use `component_name` query parameter instead.
Example:
```
import requests
requests.delete(
f"",
params={"component_name": component_name},
)
```
##### Response
400 application/json400 text/html403404
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested subscription not found
```
{
"message": "Subscription not found"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `domain_name` required | `string` path | `template.staircaseapi.com` | Domain name |
| `component_name` | `string` query | `ComponentName` | The name of the component from Marketplace |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested subscription not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error messageExample `Subscription not found` |
##### Other responses
`204`
`GET` `/subscriptions/{domain_name}/status`
#### Check Status[warning]
`components_delivery_statuses`
Subscription Status
#### Subscription Status
Retrieves a status of delivery for each subscribed component that an environment has subscribed to. Use query parameters to get status by specific component.
##### Subscription status
Status changes when subscription-specific operations occur. For example, if the Component to which you're subscribed gets an update, or you create a subscription. The following is an ordered flow for the subscription status changes.
Show the rest
| Status | Meaning |
| --- | --- |
| `INITIATED` | Subscription to a component has been created and awaiting the delivery. |
| `IN_QUEUE` | Delivery started, deployments are pending. |
| `FAILED` | Delivery failed, deployment attempts have failed. |
| `SUCCEEDED` | Delivery succeeded. |
#### Deprecation notice
Starting from December 2022
Marketplace will no longer display status entries inside the `products` and `data` arrays. Status entries will be represented in an array named `components`, and have the following changes:
| Deprecated field | Moved to |
| --- | --- |
| `products[*].product_name` | `components[*].component_name` |
| `products[*].deploy_status` | `components[*].delivery_status` |
| `products[*].using_bundle_id` | `components[*].component_publication_id` |
| `data[*].product_name` | `components[*].component_name` |
| `data[*].deploy_status` | `components[*].delivery_status` |
| `data[*].using_bundle_id` | `components[*].component_publication_id` |
In `products[*].{field name}`, `data[*].{field name}` and `components[*].{field name}` – the `[*]` notation refers to “any item of the array” of `products`, `data` or `components` accordingly.
##### Get changes
Before the new release gets rolled out, users can use `force_compact_status_report` query parameter with the value `true` (case-sensitive) to get responses as documented. When this parameter is provided, Marketplace will respond with new schema changes applied.
Here's the example on how to invoke such request:
```
import json, requests
delivery_statuses = requests.get(
f"",
params={"force_compact_status_report": json.dumps(True)},
)
```
Output example:
```
{
"domain_name": "twenty-uch.staircaseapi.com",
"components": [
{
"delivery_status": "SUCCEEDED",
"component_name": "Connector",
"last_deployment_id": "01GCD2RTN1PT5PE0NHMGV1SQ8R",
"status_updated_date": "2022-09-25T09:29:03.843986+00:00",
"component_publication_id": "01RC91SYEC28WZT714KXQPF0QD"
}
],
"page": {
"count": 1,
"next_token": null
}
}
```
#### Open endpoint
This endpoint is open. Endpoint is open, when you can omit request authorization via `x-api-key` header.
##### Response
200400403404
application/json Copy Deployment status per product
```
{
"domain_name": "dev-marketplace.staircaseapi.com",
"components": [
{
"component_name": "Assess-data",
"status_updated_date": "2021-09-20T16:01:51.141673+00:00",
"component_publication_id": "01G18AHNKFAEF3QEKTZJBTDF86",
"delivery_status": "SUCCEEDED",
"last_deployment_id": "01GCD2RTN1PT5PE0NHMGV1SQ8R"
}
],
"page": {
"count": 1,
"next_token": null
}
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `domain_name` required | `string` path | `template.staircaseapi.com` | Domain name |
| `force_compact_status_report` | `string` query | `true` | Whether or not to use the new version of status representation. Not required for the invocation. |
| `next_token` | `string` query | `eyJhZnRlcl9wcm9kdWN0X3R5cGUiOiAiU0VSVklDRSIsICJhZnRlcl9wcm9kdWN0X25hbWUiOiAiQSIsICJhZnRlcl9kb21haW5fbmFtZSI6ICI5OC51d2lueC5raW5kLmNsb3VkIn0=` | Pagination token. Works only with `force_compact_status_report` applied. |
##### Response `200``application/json`
3 fields
Deployment status per product
| Field | Type | Description |
| --- | --- | --- |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
| `domain_name` | `string` | Environment domain name.Example `template.staircaseapi.com` |
| `components` | `object[]` | The list of components with delivery statuses. |
| `component_name` | `string` | Component name.Example `Build` |
| `delivery_status` | `string` | Delivery status.`FAILED``INITIATED``IN_QUEUE``SUCCEEDED`Example `SUCCEEDED` |
| `component_publication_id` | `string` | The bundle ID of a component used in the delivery process. Can be null.Example `01G18AHNKFAEF3QEKTZJBTDF86` |
| `status_updated_date` | `string` | Last updated date.Example `2021-09-21T00:27:57.112734+00:00` |
| `last_deployment_id` | `string` | Latest available deployment ID used in delivery. Can be null.Example `01GCD2RTN1PT5PE0NHMGV1SQ8R` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`GET` `/subscriptions/{domain_name}/deployments`
#### List Deployment History
`getSubscriptionDeployments`
#### List Deployment History
Retrieves deployment history for each component in an environment.
Note: It's recommended to provide specific component name to filter out deployment logs.
##### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
200400 application/json400 text/html403404
application/json Copy Subscription deployment history by product.
```
{
"domain_name": "template.staircaseapi.com",
"logs": [
{
"deployment_status": "SUCCEEDED",
"component_name": "Build",
"created_at": "2021-05-31T17:45:00.352518+00:00",
"deployment_bundle_id": "620cc74e-4ffe-489c-955e-64e8e1693352"
},
{
"deployment_status": "SUCCEEDED",
"component_name": "Code",
"created_at": "2021-07-02T10:02:18.339430+00:00",
"deployment_bundle_id": "a48e4d44-31d0-4106-8518-1d67e0abb783"
}
],
"page": {
"count": 2,
"next_token": null
}
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested deployment logs not found
```
{
"message": "Deployment history not found"
}
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `domain_name` required | `string` path | `template.staircaseapi.com` | Domain name |
| `component_name` | `string` query | `Build` | Component name from Marketplace. If provided, Marketplace will list deployments for this component only. |
| `next_token` | `string` query | `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
| `limit` | `integer` query | `3` | Limit the count of items returned. Must be greater than or equal to 1 and less than or equal to 100. |
##### Response `200``application/json`
3 fields
Subscription deployment history by product.
| Field | Type | Description |
| --- | --- | --- |
| `domain_name` | `string` | Environment domain name.Example `template.staircaseapi.com` |
| `logs` | `object[]` | The list of deployment logs. |
| `deployment_bundle_id` | `string` | Deployment bundle ID.Example `ee537ce2-a80e-4ca6-b87b-25056677c10x` |
| `deployment_status` | `string` | Deployment status.Example `SUCCEEDED` |
| `created_at` | `string` | Deployment start invocation date.Example `2021-09-21T00:27:57.112734+00:00` |
| `component_name` | `string` | Component name.Example `Connector` |
| `page` | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested deployment logs not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error messageExample `Deployment history not found` |
`GET` `/subscriptions/environments`
#### List Environments
`getSubscribedEnvironments`
#### List Environments
Retrieves a list of subscribed environments.
##### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
400 application/json400 text/html403404
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Subscribed environments not found
```
{
"message": "Subscribed environments not found"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `next_token` | `string` query | `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
| `limit` | `integer` query | `3` | Limit the count of items returned. |
##### Response `200``application/json`
2 fields
Subscribed environments info
| Field | Type | Description |
| --- | --- | --- |
| `environments` | `string[]` | The list of subscribed environments. |
| `page` | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Subscribed environments not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error messageExample `Subscribed environments not found` |
`GET` `/subscriptions/query`
#### List Subscribers of Component
`getSubscribedEnvironmentsPerProduct`
#### List Subscribers of Component
Query Subscribers of Marketplace, subscribed to a particular component.
##### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
400 application/json400 text/html403404
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `component_name` required | `string` query | `Connector` | Component name from Marketplace |
| `next_token` | `string` query | `eyJhZnRlcl9wcm9kdWN0X3R5cGUiOiAiU0VSVklDRSIsICJhZnRlcl9wcm9kdWN0X25hbWUiOiAiQSIsICJhZnRlcl9kb21haW5fbmFtZSI6ICI5OC51d2lueC5raW5kLmNsb3VkIn0=` | Pagination token. |
| `limit` | `number` query | `50` | Limit the size of output. Must be greater than or equal to 1 and less than or equal to 100. Default values is 50 |
##### Response `200``application/json`
2 fields
Subscribed environments info
| Field | Type | Description |
| --- | --- | --- |
| `next_token` | `string` | Pagination token. |
| `subscribed_domains` | `string[]` | The list of subscribed environments. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`404`
`POST` `/listeners/{listener_kind}/subscriptions`
#### Listen to Deliveries
`create_listener`
#### Listen to Deliveries
`Listen To Deliveries` essentially creates a new listener, then binds it to a subscriber environment. The listener is a configuration of communication strategies.
If the environment, identified by `domain_name` field, does not have a Subscription associated with it, a subscription Listener can't be created for it. The following endpoint is where you can create a subscription: Create Subscription.
Show the rest
#### Listener kinds
##### `realtime`
`realtime` kind of listener solves a strategy whenever delivery of the component occurs.
Delivery of the particular component occurs when:
- Subscription was created for the subscriber environment
- Component has been installed
- Dependency of a direct subscribing component has been installed
#### Strategy kinds
##### `webhook`
`webhook` is the simplest way of notifying a listener. The strategy resolution will result in one-time webhook sent whenever an arbitrary component completes its way to the environment identified by the `domain_name`, it may fail, or it may complete successfully.
Note that, Marketplace sends an HTTP webhook using POST verb without any additional headers, such as Authorization, `x-api-key` etc.
The structure for the webhook payload is defined below:
```
{
"$schema": "",
"type": "object",
"additionalProperties": true,
"examples": [
{
"subscription": {
"elapsed_time": 495.95,
"component_name": "Connector",
"domain_name": "twenty-three.staircaseapi.com",
"status": "SUCCEEDED",
"product_id": "3acd1bb2-ee82-4504-a4fa-9e319811605b"
}
}
],
"properties": {
"subscription": {
"type": "object",
"additionalProperties": true,
"properties": {
"elapsed_time": {
"type": "number",
"description": "Represents how much it took to deliver a component."
},
"component_name": {
"type": "string",
"description": "Component name Marketplace used in delivery."
},
"domain_name": {
"type": "string",
"description": "Represents delivery target."
},
"status": {
"type": "string",
"description": "Represents delivery status.",
"enum": [
"FAILED",
"SUCCEEDED"
]
},
"product_id": {
"type": "string",
"description": "Represents the ID of the product to which the component is linked."
}
}
}
}
}
```
Please note that the schema can be extended to have new fields.
Example of the webhook payload:
```
{
"subscription": {
"elapsed_time": 495.95,
"component_name": "Connector",
"domain_name": "twenty-three.staircaseapi.com",
"status": "SUCCEEDED",
"product_id": "3acd1bb2-ee82-4504-a4fa-9e319811605b"
}
}
```
#### Open endpoint
This endpoint is open. Endpoint is open, when you can omit request authorization via `x-api-key` header.
#### Subscriber validation
Marketplace will validate `domain_name` to `api_key` attachment to verify the claim of the environment ownership. Depending on the ownership validation results, Marketplace can either abort the request or carry on with creating a listener.
##### Request
application/json Copy
```
{
"domain_name": "example-dot-com.staircaseapi.com",
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"description": "Example dot com environment component updates.",
"strategy": {
"kind": "webhook",
"webhook": {
"url": "https://example.com/partners/staircase-marketplace/webhooks/"
}
}
}
```
##### Response
400403404409422
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
application/json Copy Request conflict. Request is conflicting with the current state of application or previous requests.
```
{
"error": {
"message": "Conflict.",
"reason": "The given entity matches an existing item in the storage, thus cannot be operated on."
}
}
```
application/json Copy A 422 status code occurs when a request is well-formed, however, due to semantic errors it is unable to be processed.
```
{
"error": {
"message": "Unprocessable entity.",
"reason": "Domain name could not be validated."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `listener_kind` required | `string` path | `realtime` | Type of a listener. Can only have `realtime` as a value. |
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `domain_name` | `string` | Subscriber environment.Example `best.staircaseapi.com` |
| `description` | `string` | Description must fit into 120 characters.Example `Example description.` |
| `strategy` | `object` | Strategy used for notifying the downstream. |
| `kind`required | `string` | Communication kind.`webhook`Example `webhook` |
| `webhook`required | `object` | Webhook object represents receiving url, to which the webhook is sent. |
| `url`required | `string (uri)` | Must be a valid URL with HTTPS scheme.Example `https://google.com/staircase/marketplace/webhooks` |
| `api_key`required | `string` | API key of the subscriber. Is used for validation.Example `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404``409``422`
`DELETE` `/listeners/{listener_kind}/subscriptions/{domain_name}`
#### Remove Listener
`remove_listener`
#### Remove Listener
Removes listener for a given subscriber identified by `domain_name`. To use `Subscriber validation`, you need to provide an API key in query parameters.
#### Open endpoint
This endpoint is open. Endpoint is open, when you can omit request authorization via `x-api-key` header.
#### Subscriber validation
Marketplace will validate `domain_name` to `api_key` attachment to verify the claim of the environment ownership. Depending on the ownership validation results, Marketplace can either abort the request or carry on with deleting a listener.
##### Response
400403404422
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
application/json Copy A 422 status code occurs when a request is well-formed, however, due to semantic errors it is unable to be processed.
```
{
"error": {
"message": "Unprocessable entity.",
"reason": "Domain name could not be validated."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `listener_kind` required | `string` path | `realtime` | Type of a listener. Can only have `realtime` as a value. |
| `api_key` required | `string (uuid)` query | `` | API key, which belongs to an environment identified by `domain_name`. |
| `domain_name` required | `string` path | `template.staircaseapi.com` | Domain name |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404``422`
`GET` `/listeners/{listener_kind}/subscriptions/{domain_name}`
#### Get Listener
`get_listener`
#### Get Listener
Retrieves the information about the listener, such as strategy and listener kind. If the `api_key` declared in query parameters does not belong to a `domain_name` from path parameters, response parts such as webhook URL will be censored and have a string value of `value__hidden`.
#### Open endpoint
This endpoint is open. Endpoint is open, when you can omit request authorization via `x-api-key` header.
#### Subscriber validation
Marketplace will validate `domain_name` to `api_key` attachment to verify the claim of the environment ownership. Depending on the ownership validation results, Marketplace can either obfuscate some parts of the response or return the full information about the listener.
##### Response
200 Basic example of the response200 Example with obfuscation400403404
application/json Copy The listener has been retrieved successfully.
```
{
"listener": {
"strategy": {
"kind": "webhook",
"webhook": {
"url": "https://webhooks.staircaseapi.com/abc-webhooks"
}
},
"description": "Marketplace deliveries monitoring channel."
}
}
```
application/json Copy The listener has been retrieved successfully.
```
{
"listener": {
"strategy": {
"kind": "webhook",
"webhook": {
"url": "value__hidden"
}
},
"description": "Marketplace deliveries monitoring channel."
}
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `listener_kind` required | `string` path | `realtime` | Type of a listener. Can only have `realtime` as a value. |
| `api_key` required | `string (uuid)` query | `` | API key, which belongs to an environment identified by `domain_name`. |
| `domain_name` required | `string` path | `template.staircaseapi.com` | Domain name |
##### Response `200``application/json`
1 fields
The listener has been retrieved successfully.
| Field | Type | Description |
| --- | --- | --- |
| `listener`required | `object` | Object representing listener. |
| `domain_name` | `string` | Subscriber environment.Example `best.staircaseapi.com` |
| `description` | `string` | Description must fit into 120 characters.Example `Example description.` |
| `strategy` | `object` | Strategy used for notifying the downstream. |
| `kind`required | `string` | Communication kind.`webhook`Example `webhook` |
| `webhook`required | `object` | Webhook object represents receiving url, to which the webhook is sent. |
| `url`required | `string (uri)` | Must be a valid URL with HTTPS scheme.Example `https://google.com/staircase/marketplace/webhooks` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
### Ontology
`GET` `/ontology/families`
#### List families
`get_families`
#### List Families
Retrieve a list of families registered in catalog.
##### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
200400403404
application/json Copy List of families.
```
{
"families": [
{
"family_name": "Platform",
"family_id": "da8bc1af-848-454-bfb-14131e81a518",
"description": "Example description",
"created_at": "2022-05-25T15:53:11.237890+00:00"
}
],
"page": {
"count": 1,
"next_token": "eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN"
}
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `next_token` | `string` query | `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
| `limit` | `integer` query | `3` | Limit the count of items returned. Must be greater than or equal to 1 and less than or equal to 100. |
##### Response `200``application/json`
2 fields
List of families.
| Field | Type | Description |
| --- | --- | --- |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
| `families`required | `object[]` | Array of families. |
| `family_name`required | `object` | Name of the Family.Example `DevOps` |
| `family_id`required | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `created_at`required | `string` | Date and time of the latest modification or creation operations. String is in ISO 8601 format.Example `2022-05-25T15:53:11.237890+00:00` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`POST` `/ontology/families`
#### Create family
`create_family`
#### Create Family
Registers a new family in the ontology, returning an identifier in the response payload. Family is at the highest level of ontology. Family identifier can be used to explore categories registered within the family.
#### Naming conventions
The name of the family must fit into one word or an acronym. The name is not a unique identifier of the family. Instead, families are referenced by their unique identifiers, i.e., `family_id`. Family ID is assigned by Marketplace at the creation and is returned after successful creation.
##### Request
application/json Copy
```
{
"family_name": "Platform"
}
```
##### Response
201400403404409
application/json Copy Family was successfully created.
```
{
"family_id": "df8f01bb-848-4f54-bfb-14131e81a518"
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
application/json Copy Request conflict. Request is conflicting with the current state of application or previous requests.
```
{
"error": {
"message": "Conflict.",
"reason": "The given entity matches an existing item in the storage, thus cannot be operated on."
}
}
```
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `family_name`required | `object` | Name of the Family.Example `DevOps` |
##### Response `201``application/json`
1 fields
Family was successfully created.
| Field | Type | Description |
| --- | --- | --- |
| `family_id`required | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404``409`
`GET` `/ontology/families/{family_id}/categories`
#### List categories
`get_categories`
#### List Categories
Retrieves a list of categories for a specific Family.
##### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
200400403404
application/json Copy Return a list of categories.
```
{
"family_id": "df8f01bb-848-454-bfb-14131e81a518",
"family_name": "Platform",
"categories": [
{
"category_name": "Integrate",
"category_id": "dc8c01bb-848-454-bcb-14131e81c518",
"created_at": "2022-05-20T18:16:16.071810+00:00"
}
],
"page": {
"count": 1,
"next_token": "eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN"
}
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `family_id` required | `string (uuid)` path | `df8f01bb-848-454-bfb-14131e81a518` | Family ID. |
| `next_token` | `string` query | `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
| `limit` | `integer` query | `20` | Limit the count of items returned. |
##### Response `200``application/json`
4 fields
Return a list of categories.
| Field | Type | Description |
| --- | --- | --- |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
| `family_id`required | `string` | Unique identified of a family. |
| `family_name`required | `string` | Name of the family under which categories are located. |
| `categories`required | `object[]` | Array of categories |
| `category_id`required | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `category_name`required | `string` | Name of the category. |
| `created_at`required | `string` | Date and time of the latest modification or creation operations. String is in ISO 8601 format.Example `2022-05-25T15:53:11.237890+00:00` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`POST` `/ontology/families/{family_id}/categories`
#### Create category
`create_category`
#### Create Category
Registers a new category under the existing family in the ontology. Category is the second-highest level entity in ontology. Category gets linked to the family it has been created under.
#### Naming conventions
The name of the family must fit into one word or an acronym. The name is not a unique identifier of the category. Instead, categories are referenced by their unique identifiers, i.e., `category_id`. Category ID is assigned by Marketplace at the creation and is returned after successful creation.
##### Request
application/json Copy
```
{
"category_name": "Integrate"
}
```
##### Response
201400403404409
application/json Copy Category was successfully created.
```
{
"category_id": "dc8c01bb-848-454-bfb-14131e81a518"
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
application/json Copy Request conflict. Request is conflicting with the current state of application or previous requests.
```
{
"error": {
"message": "Conflict.",
"reason": "The given entity matches an existing item in the storage, thus cannot be operated on."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `family_id` required | `string (uuid)` path | `df8f01bb-848-454-bfb-14131e81a518` | Family ID. |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `category_name`required | `object` | Name of the Category.Example `Ship` |
##### Response `201``application/json`
1 fields
Category was successfully created.
| Field | Type | Description |
| --- | --- | --- |
| `category_id`required | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404``409`
`GET` `/ontology/categories/{category_id}/products`
#### List Products
`get_products_in_category`
#### List products
Retrieves a list of products registered in the ontology.
##### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
200400403404
application/json Copy Return a list of products.
```
{
"category_id": "dc8c01bb-848-454-bfb-14131e81a518",
"category_name": "Integrate",
"products": [
{
"product_id": "da8b01ba-848-454-bfb-14131e81a518",
"product_name": "Connector",
"created_at": "2022-05-20T18:19:16.071810+00:00"
}
],
"page": {
"count": 1,
"next_token": "eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN"
}
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `category_id` required | `string (uuid)` path | `dc8c01bb-848-454-bfb-14131e81a518` | Category ID. |
| `next_token` | `string` query | `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
| `limit` | `integer` query | `3` | Limit the count of items returned. Must be greater than or equal to 1 and less than or equal to 100. |
##### Response `200``application/json`
4 fields
Return a list of products.
| Field | Type | Description |
| --- | --- | --- |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
| `category_id`required | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `category_name`required | `string` | Name of the category under which product is located. |
| `products`required | `array` | Array of products |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`POST` `/ontology/categories/{category_id}/products`
#### Create Product
`create_product`
#### Create Product
Registers a new product under the existing category in the ontology. Product is the third-highest level entity in ontology. Product gets linked to the category it has been created under.
#### Naming conventions
The name of the product must fit into one word or an acronym. The name is not a unique identifier of the product. Instead, families are referenced by their unique identifiers, i.e., `product_id`. Product ID is assigned by Marketplace at the creation and is returned after successful creation.
##### Request
application/json Copy
```
{
"product_name": "Connector"
}
```
##### Response
201400403404409
application/json Copy Product was successfully created.
```
{
"product_id": "da8b01ba-848-454-bfb-14131e81a518"
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
application/json Copy Request conflict. Request is conflicting with the current state of application or previous requests.
```
{
"error": {
"message": "Conflict.",
"reason": "The given entity matches an existing item in the storage, thus cannot be operated on."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `category_id` required | `string (uuid)` path | `dc8c01bb-848-454-bfb-14131e81a518` | Category ID. |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `product_name`required | `object` | Name of the Product.Example `Build` |
| `category_id` | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
##### Response `201``application/json`
1 fields
Product was successfully created.
| Field | Type | Description |
| --- | --- | --- |
| `product_id`required | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404``409`
`DELETE` `/ontology/families/{family_id}`
#### Delete Family
`delete_family`
#### Delete Family
Deletes a family from the catalog. This action is permanent and cannot be undone.
#### References
Note that you cannot delete a family if there are categories registered under the family.
##### Response
400403404409
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
application/json Copy Request conflict. Request is conflicting with the current state of application or previous requests.
```
{
"error": {
"message": "Conflict.",
"reason": "The given entity matches an existing item in the storage, thus cannot be operated on."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `family_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Family ID |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404``409`
`DELETE` `/ontology/categories/{category_id}`
#### Delete Category
`delete_category`
#### Delete Category
Deletes category from the ontology. This action is permanent and cannot be undone.
#### References
Note that you cannot delete a category if there are products registered under the category.
##### Response
400403404409
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
application/json Copy Request conflict. Request is conflicting with the current state of application or previous requests.
```
{
"error": {
"message": "Conflict.",
"reason": "The given entity matches an existing item in the storage, thus cannot be operated on."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `category_id` required | `string (uuid)` path | `dc8c01bb-848-454-bfb-14131e81a518` | Category ID. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404``409`
`DELETE` `/ontology/products/{product_id}`
#### Delete Product
`delete_product`
#### Delete Product
Deletes product from the ontology. This action is permanent and cannot be undone.
#### References
Note that you cannot delete a product if there are API entries left registered under the product.
##### Response
400403404409
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
application/json Copy Request conflict. Request is conflicting with the current state of application or previous requests.
```
{
"error": {
"message": "Conflict.",
"reason": "The given entity matches an existing item in the storage, thus cannot be operated on."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID to be removed from the ontology. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404``409`
`GET` `/ontology/products/{product_id}/managed_metadata`
#### List Managed Metadata
`get_managed_metadata`
#### List Managed Metadata
Retrieves a list of managed metadata for a specific product.
#### Managed Metadata
Managed metadata is maintained by Marketplace individually for different use-cases. Example of such use-case is code assessment regulator's version hash control.
##### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
200400403
application/json Copy Return a list of managed metadata.
```
{
"product_id": "eea62230-d9fe-4b37-868a-fd7d75d3cb53",
"product_name": "Product",
"metadata_history": [
{
"metadata": {
"version_hash": "version_two"
}
},
{
"metadata": {
"version_hash": "version_one"
}
}
],
"page": {
"next_token": "cGs9UFJPRFVDVCUyM2VlYTYyMjMwLWQ5ZmUtNGIzNy04NjhhLWZkN2Q3NWQzY2I1MyZzaz1NQU5BR0VEX01FVEFEQVRBJTIzUkVWSVNJT04lMjNyZXZpc2lvbiUzQTAxSEpCVFNBNUNDUkFZR0dGMUs1MjhHQTgw",
"count": 2
}
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID. |
##### Response `200``application/json`
4 fields
Return a list of managed metadata.
| Field | Type | Description |
| --- | --- | --- |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
| `product_id`required | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `product_name`required | `string` | Canonical name of an entity in the ontology. Name must fit into one word or an acronym.Example `Identity` |
| `metadata_history`required | `object[]` | — |
| `metadata` | `object` | — |
| `version_hash` | `string` | Example `version_two` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400`
`GET` `/ontology/representation`
#### Full Representation Link
`ontology_repr`
#### Represent Full Ontology
Generates URL for the active ontology. Ontology representation describes the whole ontology.
The URL is located under a property named `ontology_url` in the response payload.
#### Example of Ontology Representation
An item within the list of entities of the corresponding entity map provides a link to an upper level entity:
- “category” is aware of the family it's created under. Use `family_id` to navigate back to family.
- “product” is aware of the category it's created under. Use `category_id` to navigate back to category.
- "configuration" is aware of the product it is registered under. Use `product_id` to navigate back to product.
- “API” is aware of the product it's registered under. Use `product_id` to navigate back to product.
- “component” is aware of the product it's created under. Use `product_id` to navigate back to product
- “price” is aware of the API it's created under. Use `product_api_identifier` to navigate back to API.
Example:
Show the rest
```
{
"families": [
{
"family_id": "965b4d6b-4c00-4c50-b321-c991d60dbf30",
"created_at": "2022-07-14T09:45:38.839462+00:00",
"family_name": "DevOps"
},
...
],
"categories": [
{
"category_id": "19a7d3ac-9203-4a5f-bdc9-df7e7951cb56",
"created_at": "2022-07-14T09:45:38.840851+00:00",
"category_name": "Delivery"
},
...
],
"products": [
{
"category_id": "19a7d3ac-9203-4a5f-bdc9-df7e7951cb56",
"created_at": "2022-07-14T09:45:38.841529+00:00",
"product_name": "Marketplace",
"product_id": "01c9df65-4c81-4278-a5b9-501a0e57b4a5"
},
...
],
"api": [
{
"product_api_name": "DescribeDeliveryAttributes",
"product_id": "01c9df65-4c81-4278-a5b9-501a0e57b4a5",
"product_api_identifier": "2b4a383c-604d-46b1-a303-b13e038ca6ed",
"product_api_type": "function",
"product_api_description": "Describe delivery attributes of a certain delivery."
},
...
],
"prices": [
{
"price_invocation_type": "single_partner",
"price_calculation_type": "average_supplier",
"price_timing_type": "completion",
"price_unit_type": "transaction",
"price_amount": 200,
"product_api_identifier": "2b4a383c-604d-46b1-a303-b13e038ca6ed",
"product_price_identifier": "98190224-9a17-4edc-a285-c1b5ee69a044",
"price_revision_identifier": "revision:01G7Y1K08YB53MAVSF14KZHTC5",
"price_amount_unit_type": "cent"
},
...
],
"components": [
{
"component_name": "Connector",
"product_id": "6ccd1bb2-ee82-4504-b4ca-9e139811506a",
"dependencies": [ "connection-datum", "connection-logger" ]
},
...
]
}
```
#### Notice on Consistency
Note that the ontology representation is regenerated once at a given rate and can be outdated for the sequential changes and link retrieval request.
Marketplace will provide ontology subscription mechanism soon.
##### Response
200400403
application/json Copy The ontology link has been regenerated successfully. And property named `ontology_url` contains it.
```
{
"ontology_url": "https://dev-marketplace-bundles-bucket-us-east-1-293107503335.s3.amazonaws.com/ontology-representation/2025-07-14?AWSAccessKeyId=&Signature=L0ML&x-amz-security-token=&Expires=1657812052"
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
##### Response `200``application/json`
1 fields
The ontology link has been regenerated successfully. And property named `ontology_url` contains it.
| Field | Type | Description |
| --- | --- | --- |
| `ontology_url`required | `string (uri)` | The URL for the ontology.Example `https://dev-marketplace-bundles-bucket-us-east-1-293107503335.s3.amazonaws.com/ontology-representation/2025-07-14?AWSAccessKeyId=&Signature=L0ML&x-amz-security-token=&Expires=1657812052` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400`
`GET` `/ontology/representation/raw`
#### Full Representation
`ontology_repr_json`
#### Represent Full Ontology
Retrieves cached ontology representation. Ontology representation describes the whole ontology.
#### Notice on Consistency
Note that the ontology representation is regenerated once at a given rate and can be outdated for the sequential changes and link retrieval request.
Marketplace will provide ontology subscription mechanism soon.
##### Response
200400403
application/json Copy The ontology link has been regenerated successfully. And property named `ontology_url` contains it.
```
{
"families": [
{
"family_name": "DevOps",
"created_at": "2022-07-13T03:38:06.744123+00:00",
"family_id": "62f5691e-7fd0-4728-ac3c-977dea07f338"
}
],
"categories": [
{
"category_name": "Shipping",
"created_at": "2022-07-13T03:38:06.801765+00:00",
"family_id": "62f5691e-7fd0-4728-ac3c-977dea07f338",
"category_id": "f06e9a78-5eca-441d-a6ae-6ec6a90e703a"
}
],
"products": [
{
"product_name": "Assess",
"product_id": "c9eb8899-73b2-4733-86fb-75bd9a1f3170",
"category_id": "f06e9a78-5eca-441d-a6ae-6ec6a90e703a",
"created_at": "2022-07-13T03:38:06.813104+00:00"
}
],
"configurations": [],
"api": [
{
"product_api_invocation_type": "analytics",
"product_api_description": "Validates a bundle of source code according to the rules configured",
"product_api_type": "function",
"product_api_name": "Assess",
"product_id": "c9eb8899-73b2-4733-86fb-75bd9a1f3170",
"product_api_identifier": "051f6aeb-d1d8-4e0c-80b5-7e59daf68521"
}
],
"prices": [
{
"price_amount_unit_type": "cent",
"price_timing_type": "completion",
"price_calculation_type": "cost_of_goods_sold",
"price_unit_type": "transaction",
"price_amount": 5,
"price_revision_identifier": "revision:01G9FDNFB2ERX0E58WX2R96TGG",
"product_api_identifier": "051f6aeb-d1d8-4e0c-80b5-7e59daf68521",
"product_price_identifier": "930e2bc5-5cb5-4210-b0c3-67e4c76548b7"
}
],
"components": [
{
"component_name": "Assess-security-data",
"product_id": "c9eb8899-73b2-4733-86fb-75bd9a1f3170",
"dependencies": [
"Assess"
]
},
{
"component_name": "Assess-staircase-data",
"product_id": "c9eb8899-73b2-4733-86fb-75bd9a1f3170",
"dependencies": [
"Assess"
]
},
{
"component_name": "Assess-swagger-data",
"product_id": "c9eb8899-73b2-4733-86fb-75bd9a1f3170",
"dependencies": [
"Assess"
]
},
{
"component_name": "Assess",
"product_id": "c9eb8899-73b2-4733-86fb-75bd9a1f3170",
"dependencies": []
}
]
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`200``400`
`GET` `/ontology/products`
#### List Products With Name Filter
`products_by_name`
#### List Products With Name Filter
Retrieves a list of products registered in the ontology, applying the provided filter for product's name. Each Product matching name is returned. Category ID is included in the product ID for the easier navigation upwards.
##### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
200400403404
application/json Copy Return a list of products.
```
{
"products": [
{
"product_id": "da8b01ba-848-454-bfb-14131e81a518",
"product_name": "Build",
"created_at": "2022-05-20T18:19:16.071810+00:00",
"category_id": "dc8c01bb-848-454-bfb-14131e81a518"
}
],
"page": {
"count": 1,
"next_token": null
}
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` query | `Build` | Component name. |
| `next_token` | `string` query | `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
| `limit` | `integer` query | `5` | Limit the count of items returned. |
##### Response `200``application/json`
2 fields
Return a list of products.
| Field | Type | Description |
| --- | --- | --- |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
| `products`required | `array` | Array of products |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`PATCH` `/ontology/{ontology_entity_typename}/{ontology_entity_id}/metadata`
#### Extend Entity Metadata
`update_any_metadata`
Update Metadata
#### Update Metadata
Updates the metadata of the given entity.
Metadata might consist of operational data, which helps to understand how Product owners manage its operations.
- Note: Marketplace appends provided metadata to the existing one, so old fields are kept.
##### Ontology Entities Eligible For Metadata
Path parameter `ontology_entity_typename` can be one of the following:
- `categories`
- `families`
- `products`
##### Request
ConnectionProductMetadataDevOpsFamilyMetadata
application/json Copy
```
{
"metadata": {
"description": "Wrap upstream API operations for multiple partners using \"Connection State Language\".",
"asana_board_id": "23349323054118939",
"asana_board_url": "https://app.asana.com/12/23349323054118939",
"codex": "https://codex.io/managed/Connector",
"documentation": "https://api.staircase.co/docs/Platform/Integrate/Connector",
"homepage": "https://api.staircase.co/docs/Platform/Integrate/Connector#root"
}
}
```
application/json Copy
```
{
"metadata": {
"description": "DevOps – Family of products, which enables you rapid software integration and delivery, providing extremely rich toolset.",
"homepage": "https://api.staircase.co/docs/DevOps#root"
}
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `ontology_entity_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Entity ID. Can be an ID for the family, product or category. |
| `ontology_entity_typename` required | `string` path | `families` | Entity typename. Can be `families`, `products` or `categories`. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `metadata`required | `one of` | Information helpful to understand operations of the product. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
`GET` `/ontology/{ontology_entity_typename}/{ontology_entity_id}/metadata`
#### Get Entity Metadata
`get_any_metadata`
Get Metadata
#### Get Metadata
Retrieves the metadata of the given entity.
Metadata might consist of operational data, which helps to understand how Product owners manage its operations.
##### Ontology Entities Eligible For Metadata
Path parameter `ontology_entity_typename` can be one of the following:
- `categories`
- `families`
- `products`
##### Response
200400403404
application/json Copy Successfully retrieved Product's Metadata.
```
{
"metadata": {
"asana_board_id": "23349323054118939",
"asana_board_url": "https://app.asana.com/12/23349323054118939",
"codex": "https://codex.io/managed/Connector",
"documentation": "https://api.staircase.co/docs/Platform/Integrate/Connector",
"homepage": "https://api.staircase.co/docs/Platform/Integrate/Connector#root"
}
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `ontology_entity_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Entity ID. Can be an ID for the family, product or category. |
| `ontology_entity_typename` required | `string` path | `families` | Entity typename. Can be `families`, `products` or `categories`. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
1 fields
Successfully retrieved Product's Metadata.
| Field | Type | Description |
| --- | --- | --- |
| `metadata`required | `one of` | Information helpful to understand operations of the product. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`PATCH` `/ontology/families/{family_id}`
#### Update Family[new]
`update_family`
Update Family
#### Update Family
Updates family identified by its identifier.
##### Request
application/json Copy
```
{
"family_name": "Mortgage"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `family_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Family ID |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `family_name`required | `string` | Canonical name of an entity in the ontology. Name must fit into one word or an acronym.Example `Identity` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
`PATCH` `/ontology/categories/{category_id}`
#### Update Category[new]
`update_category`
Update Category
#### Update Category
Updates category identified by its identifier.
##### Request
application/json Copy
```
{
"category_name": "Tools"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `category_id` required | `string (uuid)` path | `dc8c01bb-848-454-bfb-14131e81a518` | Category ID. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `category_name` | `string` | Canonical name of an entity in the ontology. Name must fit into one word or an acronym.Example `Identity` |
| `family_id` | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
`GET` `/ontology/products/{product_id}`
#### Get Product[new]
`get_product`
Get Product
#### Get Product
Retrieves product identified by its identifier.
##### Response
200400403404
application/json Copy Return a product.
```
{
"product_id": "da8b01ba-848-454-bfb-14131e81a518",
"product_name": "Connector",
"created_at": "2022-05-20T18:19:16.071810+00:00"
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID to be removed from the ontology. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
4 fields
Return a product.
| Field | Type | Description |
| --- | --- | --- |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
| `category_id`required | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `category_name`required | `string` | Name of the category under which product is located. |
| `products`required | `array` | Array of products |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`PATCH` `/ontology/products/{product_id}`
#### Update Product[new]
`update_product`
Update Product
#### Update Product
Updates product identified by its identifier.
##### Request
application/json Copy
```
{
"product_name": "Connection"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID to be removed from the ontology. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `product_name`required | `object` | Name of the Product.Example `Build` |
| `category_id` | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
### Product
`GET` `/ontology/products/{product_id}/api`
#### Get Product API With Prices[updated]
`join_product_api_with_latest_price`
Get Product API With Prices
#### Get Product API With Prices
Retrieves all registered API entries for a given product. The items in the resulting list are extended with the latest price revision.
If the API is not registered with price revision under it, there will be no price information in the item.
#### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
200400403404
application/json Copy Successfully retrieved API and price revisions.
```
{
"page": {
"count": 1,
"next_token": "eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN"
},
"product_id": "da8bc1af-848-454-bfb-14131e81a518",
"product_name": "Build",
"api": [
{
"api": {
"product_api_name": "CreateArtifactForPackage",
"product_api_description": "Creates an artifact for a given package.",
"product_api_type": "function",
"product_api_identifier": "da8bc1af-848-454-bfb-14131e81a518",
"invocation_type": "analytics"
},
"price": {
"price_amount": 10,
"price_amount_unit_type": "cent",
"price_calculation_type": "average_supplier",
"price_timing_type": "completion",
"price_unit_type": "environment",
"product_price_identifier": "da8bc1af-848-454-bfb-14131e81a518",
"price_revision_identifier": "revision:01G6N30DHYMPRKETP1ACEEXAMP"
}
}
]
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
5
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `next_token` | `string` query | `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
| `limit` | `integer` query | `5` | Limit the count of items returned. Must be greater than or equal to 1 and less than or equal to 15. If `include_prices` is `false` the limit can have a maximum value of 100. |
| `include_prices` | `string` query | `true` | Flag determines if the output should contain prices along with API entries. true by default |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
4 fields
Successfully retrieved API and price revisions.
| Field | Type | Description |
| --- | --- | --- |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
| `product_id` | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `product_name` | `object` | Name of the Product.Example `Build` |
| `api` | `object[]` | — |
| `api` | `object` | — |
| `product_api_name` | `string` | Canonical name of an entity in the ontology. Name must fit into one word or an acronym.Example `Identity` |
| `product_api_description` | `string` | Brief explanation for an API does. |
| `product_api_type` | `string` | The fundamental type of API.`configuration``function``platform`Example `function` |
| `product_api_invocation_type` | `string` | What an application endpoint does, when invoked successfully.`aggregated_partner``analytics``environment``notification``operation``proxy``single_partner`Example `analytics` |
| `product_api_identifier`required | `string` | Unique identifier for this API.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `price` | `object` | — |
| `price_amount`required | `number` | Value representing price in predefined unit.Example `10` |
| `price_amount_unit_type`required | `string` | Price unit. Must be `cent`.`cent`Example `cent` |
| `price_calculation_type`required | `string` | The price is calculated using one of the permitted pricing strategies.`average_supplier``cost_of_goods_sold``equivalent_labor_cost``maturity`Example `average_supplier` |
| `price_timing_type`required | `string` | Price is included into billing based on this defined schedule.`completion``monthly`Example `completion` |
| `price_unit_type`required | `string` | The unit of the platform where the price evaluation can be determined as relevant.`api_call``datapoint``document``environment``hour``image``page``person``person_hour``pm``pm_hour``product``seat``subscription``transaction`Example `environment` |
| `product_price_identifier`required | `object` | Newly assigned price ID.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `price_revision_identifier`required | `string` | Revision indicator.Example `revision:01G6N30DHYMPRKETP1ACEEXAMP` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`POST` `/ontology/products/{product_id}/api`
#### Register an API
`register_an_api`
#### Register an API
Registers an API for a given product. API is registered under the product. Product is referenced by its ID. APIs can serve as a basis for business value delivery or supervise the latter.
API can be referenced by Product ID and API ID pair. Product ID must be the Product ID under which the API has registered.
#### API type definition
`product_api_type` generalizes the purpose of the API. An API can have three purposes and these are allowed values:
Show the rest
- `configuration` – APIs that control the behaviors of the other APIs.
- `function` – APIs that perform functions.
- `platform `– Platform APIs are those which provide the foundation blocks required by other APIs.
#### API invocation type definition
Staircase evaluates the type of API being invoked in order to determine price. For example, an `aggregated_partner` call will cost more than a `single_partner` call because more partners are being invoked. Usually only mortgage products have `single_partner` and `aggregated_partner` API calls.
- `aggregated_partner` – Staircase APIs call multiple partner’s APIs by creating a partner invocation waterfall.
- `analytics` – Staircase sends the product results in raw report format to the customer.
- `environment` – Staircase APIs call in an environment.
- `notification` – Staircase sends a notification to the customer that the product has completed and results are ready to be viewed.
- `operation` – Staircase has basic 'function' APIs that preform specific operations, like calling product configuration.
- `proxy` – Staircase APIs are proxies of other Staircase products, usually Staircase Platform products. API calls are internal.
- `single_partner` – Staircase APIs only call one partner’s APIs when performing product functions such as data extraction or employment verification.
##### Request
application/json Copy
```
{
"product_api_name": "retrieveImageForGivenRevision",
"product_api_type": "function",
"product_api_description": "Retrieve an image for a given revision number.",
"product_api_invocation_type": "single_partner"
}
```
##### Response
201400403404
application/json Copy Action were associated with the Product successfully. List of URIs follows.
```
{
"product_api_identifier": "dc8a01fa-848-454-bfb-14131e81a518"
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `product_api_name` | `string` | Canonical name of an entity in the ontology. Name must fit into one word or an acronym.Example `Identity` |
| `product_api_description` | `string` | Brief explanation for an API does. |
| `product_api_type` | `string` | The fundamental type of API.`configuration``function``platform`Example `function` |
| `product_api_invocation_type` | `string` | What an application endpoint does, when invoked successfully.`aggregated_partner``analytics``environment``notification``operation``proxy``single_partner`Example `analytics` |
##### Response `201``application/json`
1 fields
Action were associated with the Product successfully. List of URIs follows.
| Field | Type | Description |
| --- | --- | --- |
| `product_api_identifier`required | `string` | Unique identifier for this API.Example `da8bc1af-848-454-bfb-14131e81a518` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`PATCH` `/ontology/products/{product_id}/api/{api_id}`
#### Update an API[new]
`update_an_api`
Update an API
#### Update an API
Updates chosen attributes of an API. The update request must introduce with at least one modification.
##### Request
application/json Copy
```
{
"product_api_name": "retrieveImageRevision",
"product_api_type": "platform"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID. |
| `api_id` required | `string (uuid)` path | `dc8a01fe-848-454-bfb-14131e81a518` | API ID |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `product_api_name` | `string` | Canonical name of an entity in the ontology. Name must fit into one word or an acronym.Example `Identity` |
| `product_api_description` | `string` | Brief explanation for an API does. |
| `product_api_type` | `string` | The fundamental type of API.`configuration``function``platform`Example `function` |
| `product_api_invocation_type` | `string` | What an application endpoint does, when invoked successfully.`aggregated_partner``analytics``environment``notification``operation``proxy``single_partner`Example `analytics` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
`DELETE` `/ontology/products/{product_id}/api/{api_id}`
#### Delete an API
`deregister_an_api`
Delete API
#### Delete API
Deletes an API for a given product. API can be deleted only if there is no price associated to it.
Once deleted API is never shown in product's API list.
##### Response
400403404409
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
application/json Copy Request conflict. Request is conflicting with the current state of application or previous requests.
```
{
"error": {
"message": "Conflict.",
"reason": "The given entity matches an existing item in the storage, thus cannot be operated on."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID. |
| `api_id` required | `string (uuid)` path | `dc8a01fe-848-454-bfb-14131e81a518` | API ID |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404``409`
`DELETE` `/ontology/prices/{price_id}`
#### Delete Price
`delete_price`
#### Delete Price
Permanently deletes a price. It cannot be undone. Also, immediately clears revision history.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `price_id` required | `string (uuid)` path | `bb8b01bb-848-454-bfb-14131e81a518` | Price ID. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
`GET` `/ontology/prices/{price_id}`
#### Get The Latest Price Revision
`get_latest_price`
#### Get The Latest Price Revision
Retrieves the details of the latest revision for the Price.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `price_id` required | `string (uuid)` path | `bb8b01bb-848-454-bfb-14131e81a518` | Price ID. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
7 fields
Price was successfully deleted.
| Field | Type | Description |
| --- | --- | --- |
| `price_amount`required | `number` | Value representing price in predefined unit.Example `10` |
| `price_amount_unit_type`required | `string` | Price unit. Must be `cent`.`cent`Example `cent` |
| `price_calculation_type`required | `string` | The price is calculated using one of the permitted pricing strategies.`average_supplier``cost_of_goods_sold``equivalent_labor_cost``maturity`Example `average_supplier` |
| `price_timing_type`required | `string` | Price is included into billing based on this defined schedule.`completion``monthly`Example `completion` |
| `price_unit_type`required | `string` | The unit of the platform where the price evaluation can be determined as relevant.`api_call``datapoint``document``environment``hour``image``page``person``person_hour``pm``pm_hour``product``seat``subscription``transaction`Example `environment` |
| `product_price_identifier`required | `object` | Newly assigned price ID.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `price_revision_identifier`required | `string` | Revision indicator.Example `revision:01G6N30DHYMPRKETP1ACEEXAMP` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`GET` `/ontology/products/{product_id}/api/{api_id}`
#### Retrieve an API
`retrieve_an_api`
#### Retrieve API
Retrieves an API for a given product.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID. |
| `api_id` required | `string (uuid)` path | `dc8a01fe-848-454-bfb-14131e81a518` | API ID |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
1 fields
API was successfully retrieved.
| Field | Type | Description |
| --- | --- | --- |
| `api` | `object` | API information retrieved. |
| `product_api_name` | `string` | Canonical name of an entity in the ontology. Name must fit into one word or an acronym.Example `Identity` |
| `product_api_description` | `string` | Brief explanation for an API does. |
| `product_api_type` | `string` | The fundamental type of API.`configuration``function``platform`Example `function` |
| `product_api_invocation_type` | `string` | What an application endpoint does, when invoked successfully.`aggregated_partner``analytics``environment``notification``operation``proxy``single_partner`Example `analytics` |
| `product_api_identifier`required | `string` | Unique identifier for this API.Example `da8bc1af-848-454-bfb-14131e81a518` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`PUT` `/ontology/products/{product_id}/api/{api_id}/prices`
#### Create New Price Revision
`create_price_revision`
#### Create New Price Revision
When you create a new price revision it automatically becomes the latest revision.
#### Pricing Description Style and Content
Descriptions should address the "what" of the product – what function is the product performing for the customer? It should begin with a verb that describes what function the API performs. For example: "Verify using multiple partners (waterfall)"
Show the rest The first letter in the price description is uppercase. The remaining words in the pricing description are lowercase unless the word is an acronym like API, or a proper noun like Staircase. Do not put a period or any other punctuation at the end of the pricing description (the descriptions themselves are not sentences and therefore don’t need it).
The `price_unit_type` will be shown as follows to the right of the actual cost, along with the word "per". Do not add `price_unit_type` to the description, for example "price for monthly subscription" is not a preferred description because it lists redundant information rather than tell the customers what functions they’re paying for.
If the `price_unit_type` = `transaction`, Site product will add "per transaction" to the right of the actual cost displayed. Examples:
- "$1.40 per transaction".
If the `price_unit_type` = `subscription`, `environment`, `product` or `user`, the Site product will render the description as "{price_amount (in dollars)} per {price_unit_type}, per month". Examples:
- $100 per subscription, per month
- $9.99 per environment, per month
- $5.00 per product, per month
- $3.40 per user, per month
##### Description Conventions
- If `product_api_invocation_type` = `aggregated_partner`, `description` = Invoke Product Using Multiple Partners.
- If `product_api_invocation_type` = `analytics`, `description` = Generate and Store Analytics for Reporting.
- If `product_api_invocation_type` = `environment`, `description` = Unlimited Use of Product APIs in Environment.
- If `product_api_invocation_type` = `notification`, `description` = Notify via Email and SMS.
- If `product_api_invocation_type` = `operation`, `description` = Invoke a Staircase product API.
- If `product_api_invocation_type` = `proxy`, `description` = Invoke a proxy Staircase API.
- If `product_api_invocation_type` = `single_partner`, `description` = Invoke a Product Using One Partner.
- If `price_unit_type` = `subscription`, `description` should include less than 10 words of details on what function is being performed as part of the subscription. You do not need to include the word “subscription” in the description, as this word should be visible next to the actual price.
##### Mortgage "Partner" Products Example
Mortgage products that make partner calls typically have four different types of pricing as listed in the example below.
NOTE: The environment cost that these products incur is included in the transaction cost, so there is no need to add an "environment cost" per product.
Examples:
- Credit - Verify using multiple partners (waterfall).
- Credit - Verify using one partner.
- Credit - Invoke a proxy Staircase API.
- Credit - Notify upon completion via email and SMS.
- Employment - Verify using one partner.
- Employment - Notify upon completion via email and SMS.
- Employment - Invoke a proxy Staircase API.
- Employment - Verify using multiple partners (waterfall).
- Income - Verify using multiple partners (waterfall).
- Income - Verify using one partner.
- Income - Notify upon completion via email and SMS.
- Income - Invoke a proxy Staircase API.
#### Price definition
- `price_amount` (Required|Number) – Value representing the cost. If non-integer, the value must have a fixed precision of two digits after the decimal point. The inclusive minimum value is `0.01` and the inclusive maximum is `999999.99`
- `price_amount_unit_type` (Required|String) – Value representing the unit of cost. Currently, “cent” is the only allowed value.
- `price_calculation_type` (Required|String) – Different machines of calculating Staircase price per transaction.
- `price_unit_type` (Required|String) – The unit of the platform where the price evaluation can be determined as relevant.
- `price_timing_type` (Required|String) – The price is included into the billing based on this defined schedule.
##### Enumeration variants for fields representing types.
###### price_calculation_type
Staircase determines how price per transaction should be calculated based on the average or overall supplier fee, or on the labor costs saved. For pricing related to premium support, Staircase might also consider how large or mature the customer company is.
- `average_supplier` – The cost is based on the average supplier fee.
- `cost_of_goods_sold` – The cost is based on the overall supplier fee.
- `equivalent_labor_cost` – The cost is based on the labor cost the API saves.
- `maturity` – The cost is based on how large and mature the customer is.
###### price_unit_type
Type of unit that defines which value is used as a measuring location for the calculation.
- `environment` – One charge for an environment and all the product APIs it contains. Monthly.
- `product` – A monthly charge per product. Company and Marketplace are likely to have a “Per Product” monthly charge.
- `seat` – One charge per subscriber, for functions like premium support. No limit to the number of transactions a subscriber can run in a given month.
- `subscription` – A monthly charge per product. Company and Marketplace are likely to have a “Per Product” monthly charge.
- `transaction` – One charge per API call (upon completion of transaction).
- `user` – A monthly charge per user. Setup and possibly PreApproval are likely to have a “Per User” monthly charge, where there is no limit to the number of product transactions a user can run in a given month.
- `api_call` – One charge per API call.
- `document` – One charge per document.
- `hour` – One charge per hour.
- `image` – One charge per image.
- `page` – One charge per page.
- `person` – One charge per person.
- `person_hour` – One charge per person hour.
- `pm` – One charge per product manager.
- `pm_hour` – One charge per product manager hour.
- `datapoint` – One charge per data point retrieved from the document.
###### price_timing_type
Depending on the `price_unit_type`, Staircase will charge upon `completion` or on a `monthly` basis.
###### Allowed values are:
- `completion` – Charged upon completion.
- `monthly` – Charged monthly.
###### Price Unit Types Charged Upon Completion.
Per:
- `transaction`
- `api_call`
- `document`
- `hour`
- `image`
- `page`
- `person`
- `person_hour`
- `pm`
- `pm_hour`
- `datapoint`
###### Price Unit Types Charged On a Monthly Basis.
Per:
- `environment`
- `product`
- `seat`
- `subscription`
- `user`
##### Request
application/json Copy
```
{
"price_amount": 10,
"price_amount_unit_type": "cent",
"price_calculation_type": "average_supplier",
"price_timing_type": "completion",
"price_unit_type": "environment"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID. |
| `api_id` required | `string (uuid)` path | `dc8a01fe-848-454-bfb-14131e81a518` | API ID |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Request body`application/json`
5 fields
| Field | Type | Description |
| --- | --- | --- |
| `price_amount`required | `number` | Value representing price in predefined unit.Example `10` |
| `price_amount_unit_type`required | `string` | Price unit. Must be `cent`.`cent`Example `cent` |
| `price_calculation_type`required | `string` | The price is calculated using one of the permitted pricing strategies.`average_supplier``cost_of_goods_sold``equivalent_labor_cost``maturity`Example `average_supplier` |
| `price_timing_type`required | `string` | Price is included into billing based on this defined schedule.`completion``monthly`Example `completion` |
| `price_unit_type`required | `string` | The unit of the platform where the price evaluation can be determined as relevant.`api_call``datapoint``document``environment``hour``image``page``person``person_hour``pm``pm_hour``product``seat``subscription``transaction`Example `environment` |
##### Response `200``application/json`
2 fields
Action were associated with the Product successfully. List of URIs follows.
| Field | Type | Description |
| --- | --- | --- |
| `product_price_identifier`required | `object` | Newly assigned price ID.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `price_revision_identifier`required | `string` | Revision indicator.Example `revision:01G6N30DHYMPRKETP1ACEEXAMP` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`POST` `/ontology/products/{product_id}/many_api`
#### Create Many Product Api With Prices
`create_many_api_with_prices`
#### Create Many Product Api With Prices
This endpoint allows you to register multiple API entries with prices for your product in one call.
In a single request, you can define up to 15 API with price definition merged into it. Marketplace will automatically handle creation of the API and Price for you.
If any of the following statements are true, you cannot use this endpoint:
- Provided product has at least one API associated with it.
- There are more than 15 items in a request payload.
You must use the following endpoints Register an API then Create New Price Revision.
##### Request
application/json Copy
```
[
{
"api": {
"product_api_name": "DistributeConfiguration",
"product_api_type": "function",
"product_api_description": "Distribute given configuration across all subscribed receivers."
},
"price": {
"price_amount": 10,
"price_amount_unit_type": "cent",
"price_calculation_type": "average_supplier",
"price_unit_type": "transaction",
"price_timing_type": "completion"
}
}
]
```
##### Response
200400403404
application/json Copy Prices and API entries were successfully registered. List of URIs follows.
```
[
{
"api": {
"product_api_identifier": "da8bc1af-848-454-bfb-14131e81a518"
},
"price": {
"product_price_identifier": "da8ac1ab-848-454-bfb-14131e81a518",
"price_revision_identifier": "revision:01G6N30DHYMPRKETP1ACEEXAMP"
}
}
]
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID. |
##### Response `200``application/json`
2 fields
Prices and API entries were successfully registered. List of URIs follows.
| Field | Type | Description |
| --- | --- | --- |
| `api`required | `object` | API with the identifier. |
| `product_api_identifier`required | `string` | Unique identifier for this API.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `price`required | `object` | Price definition. |
| `product_price_identifier`required | `object` | Newly assigned price ID.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `price_revision_identifier`required | `string` | Revision indicator.Example `revision:01G6N30DHYMPRKETP1ACEEXAMP` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`GET` `/ontology/products/{product_id}/components`
#### Get Product Components
`list_all_product_components`
#### Get Product Components
Retrieves all linked Components for a given Product.
#### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
200400403404
application/json Copy Successfully retrieved Components
```
{
"product_id": "d126f045-4f0d-4129-b1fb-c0e511d878e5",
"product_name": "Test",
"page": {
"next_token": null,
"count": 2
},
"components": [
"Build",
"Deploy"
]
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID |
| `next_token` | `string` query | `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
| `limit` | `integer` query | `3` | Limit the count of items returned. |
##### Response `200``application/json`
4 fields
Successfully retrieved Components
| Field | Type | Description |
| --- | --- | --- |
| `product_id` | `string (uuid)` | Canonical schema for the IDs used in the Ontology.Example `da8bc1af-848-454-bfb-14131e81a518` |
| `product_name` | `object` | Name of the Product.Example `Build` |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
| `components` | `array` | — |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`POST` `/ontology/products/{product_id}/components`
#### Link Components to Product
`link_components_to_product`
#### Link Components to Product
Links given Components to the given product. Product is referenced by its ID.
Component Link can be referenced by Product ID and Component Name pair. Product ID should be the one to which the Component was linked.
#### Component Name
Component Name should be registered in Marketplace, otherwise the request will not be fulfilled.
#### Components Number Limit
This endpoint accepts at most 15 components
##### Request
application/json Copy
```
{
"component_names": [
"Build"
]
}
```
##### Response
201400403404
application/json Copy Components were linked to the Product successfully.
```
{
"components": [
"Build"
]
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `component_names`required | `array` | Array of Component Names to be linked to the product |
##### Response `201``application/json`
1 fields
Components were linked to the Product successfully.
| Field | Type | Description |
| --- | --- | --- |
| `components` | `array` | Array of linked component names |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`DELETE` `/ontology/products/{product_id}/components/{component_name}`
#### Unlink Component from Product
`unlink_components_from_product`
#### Unlink Component from Product
Unlinks given Component from the given product. Product is referenced by its ID. Component should be previously linked to Product ID.
Once unlinked, Component is no more shown in the component list of the product.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8b01ba-848-454-bfb-14131e81a518` | Product ID |
| `component_name` required | `string` path | `Build` | Component Name |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
### Component
`GET` `/{component_registry}`
#### List Components
`listComponents__componentsRepository`
Retrieves a list of components from a particular registry.
#### Component registry
There are two types of component registries in Marketplace:
- `data` – for data configurations. Data configurations consist of static data annotations. They typically include Connection flows, Language mappings, and Language rules. Data configuration is then passed on into its target product like Connection, Language, Orchestration etc. Note that, after being deployed, data configurations cannot have runtime, thus do not have state.
- `products` – for service configurations. Service configurations can have more advanced structure. They normally consist of templates with a diversity of resource definitions like AWS Lambda Functions, Amazon Sagemaker. Note that, after being deployed, a service's resources may have the state and thus services are considered to be stateful.
So, `component_registry` path parameter can either be `products` or `data`.
Show the rest
#### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
200 Service Components List200 Data Configurations List400 application/json400 text/html403
application/json Copy Collection with list of permitted components.
```
{
"products": [
{
"name": "Build",
"description": "DevOps service for building artifacts."
},
{
"name": "Deploy",
"description": "DevOps service for service deployment."
}
],
"page": {
"next_token": null,
"count": 2
}
}
```
application/json Copy Collection with list of permitted components.
```
{
"products": [
{
"name": "Assess-data",
"description": "Data configuration for assessment product"
},
{
"name": "AUS-data",
"description": "Data configuration for AUS product"
}
],
"page": {
"next_token": null,
"count": 2
}
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `next_token` | `string` query | `cGs9RU5WSVJPTk1FTlQmc2s9RE9NQUlOJTIzYjAyMTVmNmY=` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
| `limit` | `integer` query | `15` | Limits the count of items returned |
| `component_registry` required | `string` path | `products` | Components registry. Can be 'products' or 'data'. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
1 fields
Collection with list of permitted components.
| Field | Type | Description |
| --- | --- | --- |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
`POST` `/{component_registry}`
#### Register Components
`registerManyComponents__componentsRepository`
Registers many components into the component registry of Marketplace.
#### Component registry
There are two types of component registries in Marketplace:
- `data` – for data configurations. Data configurations consist of static data annotations. They typically include Connection flows, Language mappings, and Language rules. Data configuration is then passed on into its target product like Connection, Language, Orchestration etc. Note that, after being deployed, data configurations cannot have runtime, thus do not have state.
- `products` – for service configurations. Service configurations can have more advanced structure. They normally consist of templates with a diversity of resource definitions like AWS Lambda Functions, Amazon Sagemaker. Note that, after being deployed, a service's resources may have the state and thus services are considered to be stateful.
So, `component_registry` path parameter can either be `products` or `data`.
##### Request
Service ComponentsData Components
application/json Copy
```
{
"products": [
{
"name": "Build",
"description": "DevOps service for building artifacts."
},
{
"name": "Deploy",
"description": "DevOps service for service deployment."
}
]
}
```
application/json Copy
```
{
"data": [
{
"name": "Assess-data",
"description": "Data configuration for assessment product"
},
{
"name": "AUS-data",
"description": "Data configuration for AUS product"
}
]
}
```
##### Response
201 Registered Service Components201 Registered Data Components400 application/json400 text/html403409
application/json Copy Components registry has been updated.
```
{
"products": [
{
"name": "Build",
"description": "DevOps service for building artifacts."
},
{
"name": "Deploy",
"description": "DevOps service for service deployment."
}
]
}
```
application/json Copy Components registry has been updated.
```
{
"data": [
{
"name": "Assess-data",
"description": "Data configuration for assessment product"
},
{
"name": "AUS-data",
"description": "Data configuration for AUS product"
}
]
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource already exists
```
{
"message": "Registry already contains components."
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `component_registry` required | `string` path | `products` | Components registry. Can be 'products' or 'data'. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `409``application/json`
1 fields
Resource already exists
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error messageExample `Registry already contains components.` |
##### Other responses
`201`
`PATCH` `/{component_registry}`
#### Register Component
`registerComponent__componentsRepository`
Registers a component into the component registry of Marketplace.
#### Component registry
There are two types of component registries in Marketplace:
- `data` – for data configurations. Data configurations consist of static data annotations. They typically include Connection flows, Language mappings, and Language rules. Data configuration is then passed on into its target product like Connection, Language, Orchestration etc. Note that, after being deployed, data configurations cannot have runtime, thus do not have state.
- `products` – for service configurations. Service configurations can have more advanced structure. They normally consist of templates with a diversity of resource definitions like AWS Lambda Functions, Amazon Sagemaker. Note that, after being deployed, a service's resources may have the state and thus services are considered to be stateful.
So, `component_registry` path parameter can either be `products` or `data`.
##### Request
Service ComponentData Component
application/json Copy
```
{
"products": [
{
"name": "Build",
"description": "DevOps service for building artifacts."
},
{
"name": "Deploy",
"description": "DevOps service for service deployment."
}
]
}
```
application/json Copy
```
{
"data": [
{
"name": "Assess-data",
"description": "Data configuration for assessment product"
},
{
"name": "AUS-data",
"description": "Data configuration for AUS product"
}
]
}
```
##### Response
201 Registered Service Components201 Registered Data Components400 application/json400 text/html403409
application/json Copy Components registry has been updated.
```
{
"products": [
{
"name": "Build",
"description": "DevOps service for building artifacts."
},
{
"name": "Deploy",
"description": "DevOps service for service deployment."
}
]
}
```
application/json Copy Components registry has been updated.
```
{
"data": [
{
"name": "Assess-data",
"description": "Data configuration for assessment product"
},
{
"name": "AUS-data",
"description": "Data configuration for AUS product"
}
]
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource already exists
```
{
"message": "Product ontology already exists"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `component_registry` required | `string` path | `products` | Components registry. Can be 'products' or 'data'. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`201``409`
`GET` `/{component_registry}/{name}`
#### Retrieve Component
`retrieveComponent__componentsRepository`
Retrieves component details such as description, dependencies, created and updated dates.
The response contains the URL to the latest bundle which can be used for deployment.
#### Component registry
There are two types of component registries in Marketplace:
- `data` – for data configurations. Data configurations consist of static data annotations. They typically include Connection flows, Language mappings, and Language rules. Data configuration is then passed on into its target product like Connection, Language, Orchestration etc. Note that, after being deployed, data configurations cannot have runtime, thus do not have state.
- `products` – for service configurations. Service configurations can have more advanced structure. They normally consist of templates with a diversity of resource definitions like AWS Lambda Functions, Amazon Sagemaker. Note that, after being deployed, a service's resources may have the state and thus services are considered to be stateful.
So, `component_registry` path parameter can either be `products` or `data`.
##### Response
200400 application/json400 text/html403404
application/json Copy Component has been retrieved.
```
{
"name": "Marketplace",
"bundle_url": "https://builder-api-dev-codebuilddevbucket-r016i20zh5wi.s3.amazonaws.com/marketplace-main/build/ef5844e1-885d-423b-9ead-97bac72a181c/build.zip?AWSAccessKeyId=&Signature=&x-amz-security-token=&Expires=1610711553",
"description": "Description",
"dependencies": [
"Build",
"Deploy"
],
"update_at": "2021-01-20T12:54:53.961736+00:00",
"bundle_status": "Valid",
"created_at": "2021-01-05T10:52:31.689233+00:00"
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Component not found"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `Build` | Name of product |
| `component_registry` required | `string` path | `products` | Components registry. Can be 'products' or 'data'. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
8 fields
Component has been retrieved.
| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | ASCII StringExample `Marketplace` |
| `description` | `string` | Component description.Example `DevOps service for building artifacts.` |
| `bundle_url` | `string (uri)` | Temporary URL to access resource. Needs to return 200 status on get request, to be saved.Example `https://api-data-manager-blobs-bucket.s3.amazonaws.com/00c8c9e5-dfdd-44c5-a57e-8de7a2672e2e` |
| `dependencies` | `string[]` | The list of component's dependencies. |
| `bundle_status` | `string` | Bundle status.Example `Valid` |
| `bundle_meta` | `object` | Bundle meta information. |
| `update_at` | `string` | Component updated date.Example `2021-01-09T21:36:47.785596+00:00` |
| `created_at` | `string` | Component updated date.Example `2021-01-09T21:36:47.785596+00:00` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error messageExample `Component not found` |
`PUT` `/{component_registry}/{name}`
#### Update Component
`updateComponent__componentsRepository`
#### Update Component
Uploads new bundle for a component that has already been registered in Marketplace.
##### Component registry
There are two types of component registries in Marketplace:
- `data` – for data configurations. Data configurations consist of static data annotations. They typically include Connection flows, Language mappings, and Language rules. Data configuration is then passed on into its target product like Connection, Language, Orchestration etc. Note that, after being deployed, data configurations cannot have runtime, thus do not have state.
- `products` – for service configurations. Service configurations can have more advanced structure. They normally consist of templates with a diversity of resource definitions like AWS Lambda Functions, Amazon Sagemaker. Note that, after being deployed, a service's resources may have the state and thus services are considered to be stateful.
So, `component_registry` path parameter can either be `products` or `data`.
Show the rest
#### Dependency Management
Dependencies are the mechanism of informing the Marketplace if your component depends on another component in the marketplace. It's important to understand that Marketplace Dependency Manager is not a common one. We're not talking about dependency managers, which operate on a library, package, or system level like `pip` or `cargo` do. Marketplace operates on components as dependencies of other components.
##### Types of dependencies
| Type | Description |
| --- | --- |
| Deploy-time | Deploy-time dependency is the one, which your component requires during the deployment. Before delivering a component, Marketplace will attempt to deliver its `deploy-time` dependencies first. |
| Runtime | Runtime dependency is the one, which your component requires during the runtime phase. The delivery of runtime dependencies and components can be optimized by delivering a component and its dependencies in parallel. |
Service components can define `deploy-time` dependencies (defined under `deploy_time_dependencies` field). Defining dependencies (under `dependencies` field) for data configuration components implies that they're deploy-time, hence explicit `deploy-time` (under `deploy_time_dependencies` field) dependencies are prohibited.
###### Dependency resolution
Whenever Marketplace receives a component update, Marketplace performs a shallow dependency resolution to determine the validity of your specification. During this process, Marketplace checks if there are any circular dependencies among deploy-time dependencies of your components, and if there are – you will get an error.
Suppose that the component named “Assess” has the component named “Build” as a deploy-time dependency, and the “Build” attempted to introduce a new deploy-time dependency on the “Assess” component. This will cause an error when maintainers of “Build” try to update their component, introducing a new dependency.
Error payload example:
```
{
"error": {
"message": "Invalid dependency specification. Cycle detected.",
"reason": "Cycle: Assess -> Build -> Assess"
}
}
```
Marketplace still allows circular dependencies for service components, but dependency type cannot be `deploy-time`.
##### Dependency validation
Marketplace will validate the presence and relevance of Assess signature for direct dependencies of your component. If the latest assessment rules have not passed for the component or its dependencies – Marketplace will cancel the publication.
Component's dependencies are allowed to have either latest of second latest `version_hash`.
Error payload example of dependency validation failure:
```
{
"error": {
"message": "Dependencies of Component(`Credit`) are outdated.",
"reason": [
"Component(`Connector`) a dependency of Component(`Credit`) was not signed with the latest or the second latest Assessment version hash.",
"Component(`Language`) a dependency of Component(`Credit`) was not signed with the latest or the second latest Assessment version hash."
],
"_additional_documentation": [
""
]
}
}
```
To summarize, Marketplace has the following restrictions on dependencies:
- Runtime and deploy-time dependencies cannot have intersections. This means that you cannot define a component both as a runtime and deploy-time dependency.
- Component cannot depend on itself.
- Component cannot depend on component which does not have bundles.
- Component cannot depend on component which does not exist.
- Component which is a data configuration cannot have deploy-time dependencies.
- Component and its dependencies cannot have conflicts (cycles).
- Component cannot have dependencies with outdated signature of Assessor's `version_hash`. It must be equal to second latest or latest available to Marketplace.
Use List Component Bundles endpoint to get the second latest and the latest bundle of Assessor. Example:
```
curl -X GET --location "https://.staircaseapi.com/marketplace/products/Assess/bundles?limit=2" \
-H "x-api-key: "
```
The version hash can be located by the following JSONPath: `$.bundles[*].bundle_meta.service-assessor.version_hash`.
#### Product linking
If the instance of Marketplace has products defined in its ontology, components must be linked to those products.
Use Get Product Components endpoint to get components of a product, specified by product's unique ID in `product_id` path parameter. Example:
```
curl -X GET --location "https://.staircaseapi.com/marketplace/ontology/products/{product_id}/components" \
-H "x-api-key: "
```
Use Link Components to Product endpoint to link components to a product, specified by product's unique ID in `product_id` path parameter. Example:
```
curl -X POST --location https://.staircaseapi.com/marketplace/ontology/products//components -H 'x-api-key: ' --data '{"component_names":["{component_name"]}'
```
#### Review Process
The new component configuration will be available in Marketplace only after a Review Process is completed. This process is started automatically. The Review Process status can be monitored using the `review_id` from the response.
#### Delivery
Once the review process is finished successfully, the next phase begins – update propagation.
Update propagation consists of:
- Recursive dependency resolution – every dependency of the component gets introduced to the subscriber.
- Deployment order – determined after resolving dependencies, according to dependency specifications of resolved components.
All the dependencies of the component are also components.
##### Request
application/json Copy
```
{
"bundle_url": "https://example.com/new_bundle.zip",
"description": "New cool product.",
"dependencies": [
"Build",
"Deploy"
]
}
```
##### Response
400 application/json400 text/html403404409422
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Component not found"
}
```
application/json Copy Resource already exists
```
{
"message": "Product ontology already exists"
}
```
application/json Copy Unprocessable entity
```
{
"message": "Bundle URL is not valid"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `Build` | Component name |
| `component_registry` required | `string` path | `products` | Components registry. Can be 'products' or 'data'. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Request body`application/json`
4 fields
| Field | Type | Description |
| --- | --- | --- |
| `bundle_url`required | `string` | The URL of package artifact.Example `https://example.com/new_bundle.zip` |
| `description` | `string` | Short description of product. |
| `dependencies` | `string[]` | The list of component's dependencies. |
| `deploy_time_dependencies` | `string[]` | The list of component's deploy-time dependencies. |
##### Response `202``application/json`
3 fields
New bundle accepted.
| Field | Type | Description |
| --- | --- | --- |
| `name`required | `string` | Component name.Example `Build` |
| `review_id`required | `string` | Review process ID.Example `01FG21HJ227J4RJZCJDN08KRPZ` |
| `bundle_status`required | `string` | Status of the review process.`UPLOADING_IN_PROGRESS`Example `UPLOADING_IN_PROGRESS` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error messageExample `Component not found` |
##### Response `422``application/json`
1 fields
Unprocessable entity
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Unprocessable entity error messageExample `Bundle URL is not valid` |
##### Other responses
`409`
`POST` `/{component_registry}/{name}/rollback`
#### Rollback Component
`rollbackComponent__componentsRepository`
#### Rollback Component
Reverts the component version to the previous one. This will initiate the update of the component with the previous bundle.
##### Response
400 application/json400 text/html403404409422
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Component not found"
}
```
application/json Copy Resource already exists
```
{
"message": "Product ontology already exists"
}
```
application/json Copy Unprocessable entity
```
{
"message": "Bundle URL is not valid"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `Build` | Component name |
| `component_registry` required | `string` path | `products` | Components registry. Can be 'products' or 'data'. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
3 fields
Revert process started.
| Field | Type | Description |
| --- | --- | --- |
| `name`required | `string` | Component name.Example `Build` |
| `review_id`required | `string` | Review process ID.Example `01FG21HJ227J4RJZCJDN08KRPZ` |
| `bundle_status`required | `string` | Status of the review process.`UPLOADING_IN_PROGRESS`Example `UPLOADING_IN_PROGRESS` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error messageExample `Component not found` |
##### Response `422``application/json`
1 fields
Unprocessable entity
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Unprocessable entity error messageExample `Bundle URL is not valid` |
##### Other responses
`409`
`DELETE` `/{component_registry}/{name}`
#### Delete Component
`deleteComponent__componentsRepository`
Delete a component from components registry.
Note that, in order to delete a component, you must delete all the bundles associated to it.
#### Component registry
There are two types of component registries in Marketplace:
- `data` – for data configurations. Data configurations consist of static data annotations. They typically include Connection flows, Language mappings, and Language rules. Data configuration is then passed on into its target product like Connection, Language, Orchestration etc. Note that, after being deployed, data configurations cannot have runtime, thus do not have state.
- `products` – for service configurations. Service configurations can have more advanced structure. They normally consist of templates with a diversity of resource definitions like AWS Lambda Functions, Amazon Sagemaker. Note that, after being deployed, a service's resources may have the state and thus services are considered to be stateful.
So, `component_registry` path parameter can either be `products` or `data`.
##### Response
200400 application/json400 text/html403404
application/json Copy Success delete.
```
{
"name": "Build"
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Component not found"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `Build` | Component name |
| `component_registry` required | `string` path | `products` | Components registry. Can be 'products' or 'data'. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
1 fields
Success delete.
| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | The name of productExample `Build` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error messageExample `Component not found` |
`GET` `/{component_registry}/{name}/bundles`
#### List Component Bundles
`listComponentBundles__componentsRepository`
Retrieves a list of bundles associated with the product. Each bundle contains a unique ID, URL, metadata, description and dependencies.
#### Component registry
There are two types of component registries in Marketplace:
- `data` – for data configurations. Data configurations consist of static data annotations. They typically include Connection flows, Language mappings, and Language rules. Data configuration is then passed on into its target product like Connection, Language, Orchestration etc. Note that, after being deployed, data configurations cannot have runtime, thus do not have state.
- `products` – for service configurations. Service configurations can have more advanced structure. They normally consist of templates with a diversity of resource definitions like AWS Lambda Functions, Amazon Sagemaker. Note that, after being deployed, a service's resources may have the state and thus services are considered to be stateful.
So, `component_registry` path parameter can either be `products` or `data`.
Show the rest
#### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
200400 application/json400 text/html403404
application/json Copy 200 response
```
{
"bundles": [
{
"bundle_status": "Valid",
"bundle_id": "01F2H820J56Y2FWEQCNFTYXC33",
"dependencies": [],
"bundle_url": "https://dev-marketplace-bundles-bucket-us-east-1-764911209783.s3.amazonaws.com/SERVICE/Health/01F2H820J56Y2FWEQCNFTYXC33?AWSAccessKeyId=&Signature=&x-amz-security-token=&Expires=1617654330",
"description": "",
"bundle_meta": {
"service-assessor": {
"id": "devops-code-assessor:0d5b6e9c-e7d8-48f8-970e-a82661a1c8b6",
"issuer": "https://documentation.staircaseapi.com/code-assessor",
"status": "SUCCEEDED",
"timestamp": 1617633647.7666585,
"version": "1.0.0"
},
"service-builder": {
"bundle_type": "SERVICE",
"id": "b22de381-a28d-4b3f-bae4-62b7d53b50a8",
"issuer": "https://documentation.staircaseapi.com/infra-builder",
"status": "SUCCEEDED",
"timestamp": 1617633835.1134853,
"version": "1.1"
},
"service-code": {
"commit_hash": "c47eca3d7005b26be4c3ddd3bf164e35dc5e4afe",
"id": "2d17ef8e-355c-4ffb-b933-532881a16e0b",
"issuer": "https://documentation.staircaseapi.com/code",
"status": "SUCCEEDED",
"timestamp": 1617633512.3986268,
"version": "1.1"
}
},
"uploaded_at": "2021-04-05T14:47:47.013899+00:00"
}
],
"page": [
{
"count": 1,
"next_token": null
}
]
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Component not found"
}
```
##### Parameters
5
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `Build` | Name of product |
| `next_token` | `string` query | `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
| `limit` | `integer` query | `3` | Limit the count of items returned. |
| `component_registry` required | `string` path | `products` | Components registry. Can be 'products' or 'data'. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
2 fields
200 response
| Field | Type | Description |
| --- | --- | --- |
| `bundles` | `object[]` | The list of bundles. |
| `dependencies` | `string[]` | The list of component's dependencies. |
| `bundle_status` | `string` | Bundle status.Example `Valid` |
| `bundle_url` | `string` | Bundle URL.Example `https://example.com/new_bundle.zip` |
| `bundle_id` | `string` | Bundle ID.Example `01FG21HJ227J4RJZCJDN08KRPZ` |
| `description` | `string` | Bundle description.Example `My new bundle.` |
| `bundle_meta` | `object` | Bundle meta information. |
| `uploaded_at` | `string` | Component updated date.Example `2021-01-09T21:36:47.785596+00:00` |
| `page` | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error messageExample `Component not found` |
`GET` `/{component_registry}/{name}/bundles/{bundle_id}`
#### Retrieve Component Bundle
`getComponentBundle__componentsRepository`
Retrieves component's bundle information which contains a unique ID, URL, metadata, description and dependencies.
#### Component registry
There are two types of component registries in Marketplace:
- `data` – for data configurations. Data configurations consist of static data annotations. They typically include Connection flows, Language mappings, and Language rules. Data configuration is then passed on into its target product like Connection, Language, Orchestration etc. Note that, after being deployed, data configurations cannot have runtime, thus do not have state.
- `products` – for service configurations. Service configurations can have more advanced structure. They normally consist of templates with a diversity of resource definitions like AWS Lambda Functions, Amazon Sagemaker. Note that, after being deployed, a service's resources may have the state and thus services are considered to be stateful.
So, `component_registry` path parameter can either be `products` or `data`.
##### Response
400 application/json400 text/html403404
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Component not found"
}
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `Build` | Component name |
| `bundle_id` required | `string` path | `01FG21HJ227J4RJZCJDN08KRPZ` | Bundle ID |
| `component_registry` required | `string` path | `products` | Components registry. Can be 'products' or 'data'. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
7 fields
Success response.
| Field | Type | Description |
| --- | --- | --- |
| `description` | `string` | Component description.Example `My product description.` |
| `bundle_url` | `string (uri)` | Temporary URL to access resource. Needs to return 200 status on get request, to be saved.Example `https://api-data-manager-blobs-bucket.s3.amazonaws.com/00c8c9e5-dfdd-44c5-a57e-8de7a2672e2e` |
| `dependencies` | `string[]` | The list of component's dependencies. |
| `bundle_status` | `string` | Bundle status.Example `Valid` |
| `bundle_meta` | `object` | Bundle meta. |
| `bundle_id` | `string` | Bundle ID.Example `01FG21HJ227J4RJZCJDN08KRPZ` |
| `uploaded_at` | `string` | Component updated date.Example `2021-01-09T21:36:47.785596+00:00` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error messageExample `Component not found` |
`DELETE` `/{component_registry}/{name}/bundles/{bundle_id}`
#### Remove Component Bundle
`removeComponentBundle__componentsRepository`
Removes component bundle from Marketplace.
#### Component registry
There are two types of component registries in Marketplace:
- `data` – for data configurations. Data configurations consist of static data annotations. They typically include Connection flows, Language mappings, and Language rules. Data configuration is then passed on into its target product like Connection, Language, Orchestration etc. Note that, after being deployed, data configurations cannot have runtime, thus do not have state.
- `products` – for service configurations. Service configurations can have more advanced structure. They normally consist of templates with a diversity of resource definitions like AWS Lambda Functions, Amazon Sagemaker. Note that, after being deployed, a service's resources may have the state and thus services are considered to be stateful.
So, `component_registry` path parameter can either be `products` or `data`.
##### Response
200400 application/json400 text/html403404
application/json Copy Success delete.
```
{
"bundle_id": "01F494GQZQPSEGQ8EWRXYG8SBX"
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Component not found"
}
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `name` required | `string` path | `Build` | Component name |
| `bundle_id` required | `string` path | `01FG21HJ227J4RJZCJDN08KRPZ` | Bundle ID |
| `component_registry` required | `string` path | `products` | Components registry. Can be 'products' or 'data'. |
| `x-api-key` required | `string` header | `` | Environment API Key. |
##### Response `200``application/json`
1 fields
Success delete.
| Field | Type | Description |
| --- | --- | --- |
| `bundle_id` | `string` | The bundle IDExample `01F494GQZQPSEGQ8EWRXYG8SBX` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error messageExample `Component not found` |
`GET` `/reviews/{review_id}`
#### Retrieve Review Status
`getReviewStatus`
Get information about the review of the bundle that has been uploaded.
##### Response
200400 application/json400 text/html403404
application/json Copy Success response.
```
{
"status": "SUCCEEDED",
"review_details": {
"deploy_logs": "Component has been deployed successfully."
}
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Requested resource not found
```
{
"message": "Component not found"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `review_id` required | `string` path | `01FG21HJ227J4RJZCJDN08KRPZ` | Review ID |
##### Response `200``application/json`
2 fields
Success response.
| Field | Type | Description |
| --- | --- | --- |
| `status`required | `string` | Review status.`ABORTED``FAILED``RUNNING``SUCCEEDED``TIMED_OUT`Example `SUCCEEDED` |
| `review_details` | `object` | Review details. |
| `deploy_logs` | `string` | Deploy logs from 'Review environment'. |
| `marketplace_logs` | `object` | Marketplace logs. |
| `comply_logs` | `object` | Compliance logs. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Response `404``application/json`
1 fields
Requested resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Not found error messageExample `Component not found` |
### Configuration
`POST` `/ontology/products/{product_id}/configurations`
#### Create Product Configuration
`create_configuration`
This endpoint creates Product Configuration linked to different Companies referenced to via respective `company_id` values.
#### Properties
User is expected to set arbitrary description for the configuration to facilitate clarity. `configured_product_id` is a Product that is being configured in the Configuration. Product has to be registered in Marketplace ontology.
Show the rest `configuration_product_api_id` allows to specify the API of the Product the configuration belongs to, enabling higher granularity of the configurations, distinguishing between sub-parts of the same Product.
`company_ids` is a collection of `company_id` values that current configuration is assumed to be associated with. `company_id` references Staircase Company registered in Company product.
#### External Marketplace Product Reference
User can reference products registered on external Marketplace instances by providing the environment information in `configured_product_id` property, as described in the request body schema below. For example, assume you have a product registered on some "my-env.staircaseapi.com" environment. To reference it, you can pass the below to the `configured_product_id` property:
```
"configured_product_id": {
"environment": {
"host": "my-env.staircaseapi.com",
"api_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"value": ""
}
```
Note that, once supplied with environment information, `configured_product_api_id` is also verified on the given Marketplace instance.
#### External Company Product Reference
User can reference companies registered on external Company instances by providing the environment information in `company_ids` property, as described in the request body schema below. Follows the same pattern with `configured_product_id` example above.
#### owned_by_company
For Staircase marketplace, the `owned_by_company` property is required to be set to the ID of the company that owns the configuration. ID can be retrieved from the codex post. For external Marketplace instances, the `owned_by_company` property is required but not validated.
##### Request
ExampleExternal MP ProductExternal CompanyConfiguration Product Api
application/json Copy
```
{
"owned_by_company": "01J063B3X8GEPPGKJV72Q62N26",
"configuration_description": "Credit configuration for Credit Verify Flow.",
"configured_product_id": "da8bc1af-848-454-bfb-14131e81a518",
"company_ids": [
"b31aa2d4-bebf-4b4c-b7a2-a42237a1f489"
]
}
```
application/json Copy
```
{
"owned_by_company": "01J063B3X8GEPPGKJV72Q62N26",
"configuration_description": "Credit configuration for Credit Verify Flow.",
"configured_product_id": {
"environment": {
"host": "my-env.staircaseapi.com",
"api_key": "xxxx"
},
"value": "da8bc1af-848-454-bfb-14131e81a518"
},
"company_ids": [
"b31aa2d4-bebf-4b4c-b7a2-a42237a1f489"
]
}
```
application/json Copy
```
{
"owned_by_company": "01J063B3X8GEPPGKJV72Q62N26",
"configuration_description": "Credit configuration for Credit Verify Flow.",
"configured_product_id": {
"environment": {
"host": "my-env.staircaseapi.com",
"api_key": "xxxx"
},
"value": "da8bc1af-848-454-bfb-14131e81a518"
},
"company_ids": {
"environment": {
"host": "my-env.staircaseapi.com",
"api_key": "xxxx"
},
"value": [
"b31aa2d4-bebf-4b4c-b7a2-a42237a1f489"
]
}
}
```
application/json Copy
```
{
"owned_by_company": "01J063B3X8GEPPGKJV72Q62N26",
"configuration_description": "Credit configuration for Credit Verify Flow.",
"configured_product_id": "da8bc1af-848-454-bfb-14131e81a518",
"company_ids": [
"b31aa2d4-bebf-4b4c-b7a2-a42237a1f489"
],
"configuration_product_api_id": "9cab06c2-6bd0-4333-93d6-81987e586a42"
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Product ID |
##### Request body`application/json`
6 fields
| Field | Type | Description |
| --- | --- | --- |
| `owned_by_company`required | `string` | Company ID that owns the configuration. |
| `configuration_description`required | `string` | Arbitrary description for the configuration. Limited by 300 symbols. |
| `configuration_product_api_id` | `string` | API of the Product the configuration belongs to. |
| `configured_product_id`required | `one of` | Allows referencing either local or external MP product |
| `configured_product_api_id` | `string` | Product API that is being configured |
| `company_ids`required | `one of` | Allows referencing either local or external Company product |
##### Response `201``application/json`
1 fields
Product Configuration has been successfully created.
| Field | Type | Description |
| --- | --- | --- |
| `configuration_id` | `string` | Configuration ID that references created Configuration. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`GET` `/ontology/products/{product_id}/configurations`
#### Retrieve Product Configurations
`retrieve_configurations`
Allows to retrieve all Product Configurations created in the environment. `configured_product_id` query value can be specified to filter and retrieve only configurations where specific Product is being configured.
#### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
200400403404
application/json Copy Product Configurations have been retrieved successfully.
```
{
"configurations": [
{
"configuration_description": "first_configuration",
"configured_product_id": "da8bc1af-848-454-bfb-14131e81a518",
"owned_by_company": "01J063B3X8GEPPGKJV72Q62N26",
"company_ids": [
"01GJXYCAJ6YSJM8MFM3SPKE5HZ",
"01GJXYCAJ6YSJM8MFM3SPGP5HS"
],
"configuration_id": "3d25a250-795b-44db-9cfb-09260fbc9170",
"configured_product_api_id": "7a4fbde5-7452-4099-8af7-ea9e648c89a7"
},
{
"configuration_description": "second_configuration",
"configured_product_id": "da8bc1af-848-454-bfb-14131e81a518",
"owned_by_company": "01J063B3X8GEPPGKJV72Q62N26",
"company_ids": [
"01GJXYCAJ6YSJM8MFM3SPKEPOS"
],
"configuration_id": "02beaf9c-0e1e-408a-8f71-6bb58f0b29d4",
"configured_product_api_id": "7a4fbde5-7452-4099-8af7-ea9e648c89a7"
}
],
"page": {
"count": 2,
"next_token": null
}
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
4
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Product ID |
| `limit` | `integer` query | `10` | Configurations limit |
| `next_token` | `string` query | `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
| `configured_product_id` | `string` query | `da8bc1af-848-454-bfb-14131e81a518` | Product that was configured by Configuration |
##### Response `200``application/json`
2 fields
Product Configurations have been retrieved successfully.
| Field | Type | Description |
| --- | --- | --- |
| `configurations` | `array` | Collection of retrieved Configurations |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`DELETE` `/ontology/products/{product_id}/configurations/{configuration_id}`
#### Delete Product Configuration
`delete_configuration`
This endpoint deletes Product Configuration referenced by its `configuration_id`.
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Product ID |
| `configuration_id` required | `string` path | `da8bc1af-848-454-bfb-14131e81a518` | Configuration ID |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
`GET` `/ontology/products/{product_id}/configurations/{configuration_id}`
#### Retrieve Product Configuration
`retrieve_configuration`
This endpoint retrieves Product Configuration referenced by its `configuration_id`.
##### Response
200400403404
application/json Copy Product Configuration has been successfully retrieved.
```
{
"configuration_description": "first_configuration",
"configured_product_id": "da8bc1af-848-454-bfb-14131e81a518",
"owned_by_company": "01J063B3X8GEPPGKJV72Q62N26",
"company_ids": [
"01GJXYCAJ6YSJM8MFM3SPKE5HZ",
"01GJXYCAJ6YSJM8MFM3SPGP5HS"
],
"configuration_id": "3d25a250-795b-44db-9cfb-09260fbc9170",
"configured_product_api_id": "7a4fbde5-7452-4099-8af7-ea9e648c89a7"
}
```
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Product ID |
| `configuration_id` required | `string` path | `da8bc1af-848-454-bfb-14131e81a518` | Configuration ID |
##### Response `200``application/json`
1 fields
Product Configuration has been successfully retrieved.
| Field | Type | Description |
| --- | --- | --- |
| `configuration` | `object` | Contains Configuration information |
| `owned_by_company` | `string` | Company ID that owns the ConfigurationExample `01J063B3X8GEPPGKJV72Q62N26` |
| `configuration_description`required | `string` | Arbitrary configuration description |
| `configuration_product_api_id` | `string` | API of the Product the configuration belongs to. |
| `configured_product_id`required | `string` | Product configured by Configuration |
| `configured_product_api_id` | `string` | Product API configured by Configuration |
| `company_ids`required | `string[]` | Collection of `company_id` values |
| `configuration_id`required | `string` | Configuration ID used to reference this Configuration |
| `configured_product_host` | `string` | Host environment where the configured Product is registered. |
| `company_host` | `string` | Host environment referenced by the Companies attached to Configuration. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`PATCH` `/ontology/products/{product_id}/configurations/{configuration_id}`
#### Extend Product Configuration
`extend_configuration`
This endpoint enables users to add Company(s) to the given Configuration or to update other properties of it. Configuration is referenced by `configuration_id` in the path. Company(s) to be added must be registered in local Staircase Company product. See the request schema for referencing Companies from the external Staircase Company product.
#### Warning If `company_ids` are to be updated and the given environment does not match already attached companies' environment, the request is rejected.
#### owned_by_company
For Staircase marketplace, the `owned_by_company` property is required to be set to the ID of the company that owns the configuration. ID can be retrieved from the codex post. For external Marketplace instances, the `owned_by_company` property is required but not validated.
##### Request
ExampleExternal CompanyExternal MP Product
application/json Copy
```
{
"owned_by_company": "01J063B3X8GEPPGKJV72Q62N26",
"company_ids": [
"b31aa2d4-bebf-4b4c-b7a2-a42237a1f489"
]
}
```
application/json Copy
```
{
"owned_by_company": "01J063B3X8GEPPGKJV72Q62N26",
"company_ids": {
"environment": {
"host": "my-env.staircaseapi.com",
"api_key": "xxxx"
},
"value": [
"b31aa2d4-bebf-4b4c-b7a2-a42237a1f489"
]
}
}
```
application/json Copy
```
{
"owned_by_company": "01J063B3X8GEPPGKJV72Q62N26",
"configured_product_id": {
"environment": {
"host": "my-env.staircaseapi.com",
"api_key": "xxxx"
},
"value": "da8bc1af-848-454-bfb-14131e81a518"
}
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Product ID |
| `configuration_id` required | `string` path | `da8bc1af-848-454-bfb-14131e81a518` | Configuration ID |
##### Request body`application/json`
6 fields
| Field | Type | Description |
| --- | --- | --- |
| `owned_by_company` | `string` | Company ID that owns the configuration.Example `01J063B3X8GEPPGKJV72Q62N26` |
| `configured_product_id` | `one of` | Allows referencing either local or external MP product |
| `configured_product_api_id` | `string` | Configured Product API ID. Should be given in pair with `configured_product_id`. |
| `company_ids` | `one of` | Allows referencing either local or external Company product |
| `description` | `string` | Arbitrary configuration description to replace prior one. |
| `configuration_product_api_id` | `string` | API of the Product the configuration belongs to. |
##### Response `200``application/json`
1 fields
Product Configuration has been successfully extended.
| Field | Type | Description |
| --- | --- | --- |
| `configuration` | `object` | Contains Configuration information |
| `owned_by_company` | `string` | Company ID that owns the ConfigurationExample `01J063B3X8GEPPGKJV72Q62N26` |
| `configuration_description`required | `string` | Arbitrary configuration description |
| `configuration_product_api_id` | `string` | API of the Product the configuration belongs to. |
| `configured_product_id`required | `string` | Product configured by Configuration |
| `configured_product_api_id` | `string` | Product API configured by Configuration |
| `company_ids`required | `string[]` | Collection of `company_id` values |
| `configuration_id`required | `string` | Configuration ID used to reference this Configuration |
| `configured_product_host` | `string` | Host environment where the configured Product is registered. |
| `company_host` | `string` | Host environment referenced by the Companies attached to Configuration. |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`GET` `/ontology/configurations`
#### List Configurations by Company
`list_configurations_by_company`
This endpoint retrieves Configurations registered under all Ontology Products filtering by `company_id`. Allows understanding and tracing how and where is Staircase integrating with Partners registered in Company product.
#### Pagination by token
This endpoint supports pagination by token. If you receive a non-null value for 'next_token' under the "page" collection in response payload, to get the next page, you will have to pass 'next_token' in the following request as query parameter
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `limit` | `integer` query | `10` | Configurations limit |
| `company_id` | `string` query | `01GJYN5EY5YACHCH071C9KBTR9` | Company ID registered in Company Product |
| `next_token` | `string` query | `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` | Token used for paginating the request. Refer to the description of this endpoint to read more. |
##### Response `200``application/json`
2 fields
Configurations have been retrieved successfully.
| Field | Type | Description |
| --- | --- | --- |
| `configurations` | `object[]` | Collection of retrieved Configurations |
| `product_id` | `string (uuid)` | Product ID |
| `configuration_id` | `string` | Configuration ID used to reference this Configuration |
| `page`required | `object` | Page information. Contains basic information of the current page returned. |
| `count`required | `integer` | Count of items that were retrieved for this page.Example `1` |
| `next_token`required | `string` | If this field exists in the page information collection, it means you can continue querying for other items, using this token in the query parameters of the following request.Example `eNolzLEKwkAQRdFfeZnGRvwAWxtBbOwsh2TcXYxvZJ2NBPHfNVpduMV5yf4gW8k2d5i9rSbDxRsHKGH6CKvfpoRCRDYctV4t7qP2hsH7djOGRnHKWk4LtHOmqtHG3+1w/ptPJ+iRC9NG3h89BijN` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`400``404`
`DELETE` `/ontology/products/{product_id}/configurations/{configuration_id}/companies`
#### Delete Company(s) from Configuration[new]
`delete_company_from_configuration`
Delete Product Configuration
This endpoint deletes given `company_ids` from the Product Configuration referenced by `configuration_id`. At least 1 Company should be attached to Configuration, so requests to delete all companies are rejected.
##### Request
application/json Copy
```
{
"company_ids": [
"b31aa2d4-bebf-4b4c-b7a2-a42237a1f489"
]
}
```
##### Response
400403404
application/json Copy Bad request syntax. Request payload does not exist or malformed.
```
{
"error": {
"message": "Bad Request",
"reason": [
"\"\" is less than 1 character."
]
}
}
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy Resource not found. Resource you were looking for was not found.
```
{
"error": {
"message": "Not Found",
"reason": "Nothing matches the given URI."
}
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_id` required | `string (uuid)` path | `da8bc1af-848-454-bfb-14131e81a518` | Product ID |
| `configuration_id` required | `string` path | `da8bc1af-848-454-bfb-14131e81a518` | Configuration ID |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `company_ids`required | `string[]` | Collection of `company_id` values |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`204``400``404`
### Marketplace Instance
`PUT` `/settings`
#### Update Settings
`updateConfiguration`
Custom Settings
Configures settings for the instance of Marketplace.
| Configuration attribute | Attribute type | Description | Default |
| --- | --- | --- | --- |
| `review_api_key` | API key | Review API key is used for the review process done as a part of publication acceptance. Review process details are not disclosed. If not present publication functionality is not available. | Nothing |
| `self_cleaning_review_api_key` | API key | Second Review API key is used for the review process done as a part of publication acceptance. Optional. The Marketplace will own this environment and perform environment cleaning daily. Cleaning will delete all the data and components deployed on this environment. This environment should not be used for anything except the review process. | Nothing |
| `site_api_key` | API key | Site API key is used for the bundle distribution into Site product located in different location, where bundle's documentation is presented. If not present distribution is cancelled. | Nothing |
| `env_administrator_domain_name` | Domain name | Environment administrator is used to operate deliveries into subscriber environments. | Local environment |
| `env_administrator_api_key` | API key | Environment administrator is used to operate deliveries into subscriber environments. | Local environment |
| `comply_auth_domain_name` | Domain name | Used for authentication user through `Comply Authentication`. | Nothing |
| `code_assessment_regulator` | Regulator | Used for code assessment regulator. | Nothing |
In order to get your own Marketplace instance running, you will have to provide the following required settings:
Show the rest
- `review_api_key` – this will affect publications and review process.
- `env_administrator_domain_name` - this will affect delivery and settings validation.
- `env_administrator_api_key` - this will affect delivery and settings validation.
It is important to note that Environment administrator is a regulatory authority, which can only be located in one environment.
You can check the status of your settings at Check Status.
#### Regulators
Regulators are products that are used for variety of purposes, including code assessment, compliance, and security. The main use-case for regulators is regulator's version hash validation. Currently, Marketplace is able to integrate with the following regulators:
##### Assess
Assess product is a code assessment tool that is used to assess the quality, best-practise conformance, and security of the code that is being published to Marketplace.
Marketplace will store the history of changes to `version_hash` produced in Assess products' signature. Whenever a component of a product gets published, Marketplace will check the `version_hash` of the component, and compare it to the latest valid `version_hash` stored in Marketplace.
Note: Component's dependencies will also be validated. Dependencies must have the latest and previously latest version hash.
###### Updating `version_hash`
Whenever a component linked to Assess product gets published, Marketplace will look for changes in the `version_hash`. If the `version_hash` has changed, Marketplace will store it as the latest valid `version_hash`.
If the Assess regulator is not defined, Marketplace will not check the `version_hash` of the publishing component.
##### Registering Regulator
- Register a new product in ontology, if not registered already
##### Secondary review.
In order to have a secondary review, you need to provide `self_cleaning_review_api_key`. This key will be used for the review process done as a part of publication acceptance. The Marketplace will own this environment and perform environment cleaning daily. Cleaning will delete all the data and components deployed on this environment. This environment should not be used for anything except the review process. Purpose of this environment is to have a clean environment for the review process to validate that the component can be deployed into the fresh environment.
##### Request
application/json Copy
```
{
"review_api_key": "03660bf2-535a-4639-8df2-24322c1d7233",
"env_administrator_api_key": "38ad8edc-1e77-4d73-aff7-c38adb05d78e",
"env_administrator_domain_name": "template.staircaseapi.com",
"site_api_key": "16a75805-acd5-4dca-9ed9-f267a05b330b"
}
```
##### Response
200400 application/json400 text/html403422
application/json Copy Configuration successfully updated.
```
{
"message": "configuration successfully updated"
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy A 422 status code occurs when a request is well-formed, however, due to semantic errors it is unable to be processed.
```
{
"error": {
"message": "Unprocessable entity.",
"reason": "Domain name could not be validated."
}
}
```
##### Request body`application/json`
7 fields
| Field | Type | Description |
| --- | --- | --- |
| `review_api_key` | `string` | API key for Review environment.Example `03660bf2-535a-4639-8df2-24322c1d7233` |
| `self_cleaning_review_api_key` | `string` | API key for secondary review environment. Optional.Example `cf9e3809-0ca5-4f16-90f4-92fe612211e9` |
| `env_administrator_api_key` | `string` | API key for Environment Administrator environment.Example `38ad8edc-1e77-4d73-aff7-c38adb05d78e` |
| `env_administrator_domain_name` | `string` | Domain name of Environment Administrator environment.Example `template.staircaseapi.com` |
| `site_api_key` | `string` | API key for Site environment.Example `16a75805-acd5-4dca-9ed9-f267a05b330b` |
| `comply_auth_domain_name` | `string` | Environment domain name, where the "Comply" product runs.Example `no-tr.auth-gateway.staircaseapi.com` |
| `code_assessment_regulator` | `object` | Code assessment regulator. |
| `regulator_product_identifier`required | `string` | Product identifier of regulator.Example `dbcf20b7-0ea6-4bc5-898c-65f51e2d4686` |
##### Response `200``application/json`
1 fields
Configuration successfully updated.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Configuration updating status.Example `Configuration successfully updated` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`422`
`GET` `/settings/status`
#### Check Status
`checkInstanceStatus`
Retrieves the status of the Marketplace installed on your environment. Endpoint validates settings and returns the statuses.
| Settings status | Marketplace operation | When non-operational |
| --- | --- | --- |
| `site_publication` | Site publication | Bundles are not published into Site, and hence documentation is not updated |
| `component_publication` | Bundle distribution | Marketplace cannot review new component bundles |
| `secondary_review_environment_status` | Bundle distribution | Marketplace cleans secondary review environment daily. During the cleaning, publications are not possible. |
| `code_assessment_regulator` | Code assessment regulator | Marketplace cannot validate component's `version_hash` |
#### FAQ
##### What do I have to do if my `site_publication` is non-operational?
Site publications are not a required part of Marketplace publication channel, so it won't affect bundle publication. However, if you're expecting to see documentation updates, we recommend you to configure `site_api_key` via Update Settings
Show the rest
##### What do I have to do if my `component_publication` is non-operational?
Component publication is at the core of continuous delivery in Marketplace. If non-operational, it does not review component updates, which will block continuous delivery of the component. Note that Marketplace might still be able to deliver previously uploaded component bundles.
##### Response
200400 application/json400 text/html403422
application/json Copy Status information container.
```
{
"status": {
"site_publication": {
"is_operational": true
},
"component_publication": {
"is_operational": true
}
}
}
```
application/json Copy Request data failed validation
```
{
"message": "Missing data for required field"
}
```
text/html Copy Request data failed validation
```
400 Bad Request
```
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
application/json Copy A 422 status code occurs when a request is well-formed, however, due to semantic errors it is unable to be processed.
```
{
"error": {
"message": "Unprocessable entity.",
"reason": "Domain name could not be validated."
}
}
```
##### Response `200``application/json`
1 fields
Status information container.
| Field | Type | Description |
| --- | --- | --- |
| `status` | `object` | Collection of resources and their statuses. |
| `site_publication`required | `object` | Status container. |
| `is_operational`required | `boolean` | Flag determines if the resource is operational.Example `true` |
| `component_publication`required | `object` | Status container. |
| `is_operational`required | `boolean` | Flag determines if the resource is operational.Example `true` |
| `code_assessment_regulator` | `object` | Status container. |
| `is_operational`required | `boolean` | Flag determines if the resource is operational.Example `true` |
| `secondary_review_environment_status` | `string` | Secondary review environment status.`Operational``NotSet``CleaningInProgress``EnvironmentBroken`Example `Operational` |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Bad request error messageExample `Missing data for required field` |
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`422`
`GET` `/settings/schema`
#### Retrieve Settings Schema[new]
`retrieveSettingsSchema`
Retrieve Settings Schema
Retrieves the relevant Marketplace Settings schema. Example response schema:
```
{
"$schema": "",
"definitions": {
"ConfigureMarketplaceSchema": {
"type": "object",
"properties": {
"comply_auth_domain_name": {
"title": "comply_auth_domain_name",
"type": "string",
"description": "Environment domain name, where the \"Comply\" product runs.",
"pattern": "(^[a-zA-Z0-9]+([a-zA-Z0-9-]+\\.[a-zA-Z0-9-]+){1,61})*[a-zA-Z0-9]+\\.[a-zA-Z]{2,}$"
},
"env_administrator_api_key": {
"title": "env_administrator_api_key",
"type": "string",
"description"Show the rest;: "API key for Environment Administrator environment.",
"minLength": 1
},
"env_administrator_domain_name": {
"title": "env_administrator_domain_name",
"type": "string",
"description": "Domain name of Environment Administrator environment.",
"pattern": "(^[a-zA-Z0-9]+([a-zA-Z0-9-]+\\.[a-zA-Z0-9-]+){1,61})*[a-zA-Z0-9]+\\.[a-zA-Z]{2,}$"
},
"quicksight_api_key": {
"title": "quicksight_api_key",
"type": "string",
"minLength": 1
},
"review_api_key": {
"title": "review_api_key",
"type": "string",
"description": "API key for Review environment.",
"minLength": 1
},
"site_api_key": {
"title": "site_api_key",
"type": "string",
"description": "API key for Site environment.",
"minLength": 1
}
},
"additionalProperties": false
}
},
"$ref": "#/definitions/ConfigureMarketplaceSchema"
}
```
##### Response
application/json Copy Request is forbidden, API key is not valid
```
{
"message": "Your API key is not valid, please refresh it."
}
```
##### Response `403``application/json`
1 fields
Request is forbidden, API key is not valid
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Forbidden error messageExample `Your API key is not valid, please refresh it.` |
##### Other responses
`200`
## Errors
`400``403``404``409``422`
## More in Distribution
- Previous product: Host
- Next product: Setup