Ochre General API
Ricardo Pinto • ochreapi
Help
Apiary Powered Documentation
Sign in with Apiary account.
Apiary Powered Documentation
Sign in with Apiary account.
This document will expose all information related with all resources and actions.
All endpoints are secured by default and can be accessed specifying a valid access token on every request.
Access tokens can be issued by the Ochre Auth service:
All API requests need to include the Authorization header with the token of Bearer type.
curl -X POST -d "client_id=[as provided]&client_secret=[as provided]&grant_type=client_credentials" https://auth.ochre.io/oauth2/token
Access token TTL : 7200 seconds
A new token should be fetched upon expiration
curl -X GET \
https://api.ochre.io/v1/music/artists \
-H 'Authorization: Bearer [stored from previous ochre auth call]' \
-H 'Host: api.ochre.io'
resources - [api domain]/homepage/stores/{id}/[sub resources]
url style - spinal-case ex: [api domain]/player/products/{id}/sub-resources
json properties style - camelCase
POST = create
GET = Read
PUT = Update/Replace
PATCH = Update/Modify
DELETE = Delete
Location related information will be picked up and aggregated on every request. This will be used to expose the correspondent data formats like currency and item availability. For server-to-server implementation that info needs to me mirrored from the original client request. That can be done by specifying the following headers:
X-Client-IP
X-Client-Currency (ISO 4217)
X-Client-Country-Code2 (ISO Alpha-2)
All endpoints that return images hosted by ochre will react to image_size GET param. This will return all the images from a given response matching the size specified, if available. By default the api will return small images.
xl2000l1000m500s250xs125xxs80Sample request: /music/releases/96596?image_size=m
This will return the artwork as a 500x500 image
A space represents the umbrella for all CMS based endpoints. It will hold general information about the purpose of all its sub-resources like view and modules Allows searching, getting the profile and sub-resources.
Allows actions on the spaces collection.
| name | space name (starting by) |
|---|---|
| type | space type
|
| owner_id | owner id |
| owner_name | owner name |
| page | page number |
| limit | maximum number of records per page. |
Allows actions on a specific space.
| id | space id |
|---|
Lists all available navigation items for a given space. The results will include a structure that may hold more complex navigation structures with sub-items.
| id | space id |
|---|---|
| page | page number |
| limit | maximum number of records per page. |
| group_id | navigation group id |
Lists all views that belong the the given space.
Allows all filters from the page search apart from the space_id. This param will be ignored.
| id | space id |
|---|---|
| type | view type
|
| reference_type | reference type
|
| reference_id | reference id |
| slug | view slug |
| title | view title (starting by) |
| page | page number |
| limit | maximum number of records per page |
The view resource represents the customisable structure that will be used to organise the data through different modules. Using views will allow relying on ochre-platform tools to setup content and its disposition.
Allows actions on the view collection. As a GET request it will only allow to filter by one reference.
| space_id | space id |
|---|---|
| type | view type
|
| reference_type | reference type
|
| reference_id | reference id |
| slug | view slug |
| title | view title (starting by) |
| page | page number |
| limit | maximum number of records per page |
Allows actions on a specific view.
| id | view id |
|---|
Lists all modules associated with the given view.
This endpoint allows all module collection filters apart from view_id.
| id | page id |
|---|---|
| title | module title (starting by) |
| type | module type
|
| page | page number |
| limit | maximum number of records per page |
The category will allow to search modules, get a specific module profile as well as the inner items.
Allows action on the module collection.
| view_id | view id |
|---|---|
| title | module title (starting by) |
| type | module type Modules available are:
|
| page | page number |
| limit | maximum number of records per page |
Gets a module profile
Lists content items associated with the given module
| id | |
|---|---|
| page | page number |
| limit | maximum number of records per page |
This category exposes the store resource. It will allow searching stores and getting the related sub-resources.
Allows actions on the store collection.
| page | page number |
|---|---|
| limit | maximum number of records per page |
Gets a store profile.
This category allows exposing all product related data. It's possible search products, get a product profile and its sub-resources.
Allows actions on the product collection.
| store_id | filter by matching store |
|---|---|
| catalog_id | restrict by the main catalog id |
| group_id | allows grouping results by product group id |
| variant_group_i | allows grouping results by variant group id |
| title | filter product title (starting by) |
| type | filter by type
|
| reference_type | reference type
|
| reference_id | reference id |
| from | date string with format "yyyyMMdd" |
| to | date string with format "yyyyMMdd" |
| format | format title, ex: "vinyl", "mp3", "cd" |
| universe | universe name
|
| distribution | distribution type
|
| variant | product variant name (mainly for clothing), ex: xs, s, l, xl, ... |
| allow_preorder | show products based on their preorder permissions |
| page | page number |
| limit | maximum number of records per page |
Gets a given product resource.
Check for the given product stock and territory availability. This will gather the location data from the request by ip or custom location headers.
Lists all inner products included on for a given bundle product.
| id | product id |
|---|---|
| page | page number |
| limit | maximum number of records per page |
This category exposes the cart resource and allows managing carts and their items. Cart results and their items will be restricted by store and requesting user. The specified access token will set the results available.
Allows actions on the cart collection.
Creates a new cart resource.
| store_id | store id |
|---|
Gets a specific cart profile. Carts will include an estimated postage cost associated.
Allows action on the items that belong to a given cart.
| id | cart id |
|---|---|
| page | page number |
| limit | maximum number of records per page |
| id | cart id |
|---|
Allows actions on a specific cart item. Discounts will be calculated taking in consideration the vouchers that may be associated with the cart.
| id | cart id |
|---|---|
| item_id | cart item id |
When accepted the full updated resource will be returned. Only quantities may be updated.
| id | cart id |
|---|---|
| item_id | cart item id |
| id | cart id |
|---|---|
| item_id | cart item id |
Allows actions on the voucher list that belong to the given cart.
| id | cart id |
|---|---|
| page | page number |
| limit | maximum number of records per page |
Allows access to a filterable order collection. Results will be pulled from all catalogs to which the token has access to.
| store_ids | List of store ids split by |
|---|---|
| user_ids | List of user ids (customer ids) split by |
| created_from | Initial date created to filter from (including)
|
| created_to | Limit date created (excluding)
|
| updated_from | Initial date updated to filter from (including)
|
| updated_to | Initial date created (excluding)
|
| total_min | Initial value to filter from (including) |
| total_max | Limit value to filter to (including) |
| page | page number |
| limit | maximum number of records per page |
Gets the order main object based on the id specified.
Allows access to the order item collection that belong to the specified order id.
The purchase order id will be inferred based on the URI so the order level related filters will be restricted will be ignored.
| id | |
|---|---|
| created_from | Initial date created to filter from (including)
|
| created_to | Limit date created (excluding)
|
| total_min | Initial value to filter from (including) |
| total_max | Limit value to filter to (including) |
| quantity_min | Initial value to filter from (including) |
| quantity_max | Limit value to filter to (including) |
| page | Page number |
| limit | Maximum number of records per page |
Allows access to a filterable order item collection. Results will be pulled from all catalogs to which the token has access to.
| store_ids | List of store ids split by |
|---|---|
| user_ids | List of user ids (customer ids) split by |
| order_id | Purchase order id |
| order_number | Purchase order number string |
| created_from | Initial date created to filter from (including)
|
| created_to | Limit date created (excluding)
|
| total_min | Initial value to filter from (including) |
| total_max | Limit value to filter to (including) |
| quantity_min | Initial value to filter from (including) |
| quantity_max | Limit value to filter to (including) |
| page | page number |
| limit | maximum number of records per page |
Gets the order item main object based on the id specified.
Handles all label related data.
Allows action on the label collection.
| page | page number |
|---|---|
| limit | maximum number of records per page |
Gets a label profile.
Handles all information related with artists
Allows actions on the artist collection.
| name | artist name (contains criteria) |
|---|---|
| active | artist status
|
| catalog_id | main catalog id |
| page | page number |
| limit | maximum number of records per page |
Gets an artist profile.
Lists releases from the given artist.
| id | artist id |
|---|---|
| title | release title (starting by) |
| label_id | label id |
| catalog_id | catalog id |
| from | release date string with format "yyyyMMdd" |
| to | release date string with format "yyyyMMdd" |
| page | page number |
| limit | maximum number of records per page |
Lists tracks from the given artist.
| id | artist id |
|---|---|
| release_id | release id |
| page | page number |
| limit | maximum number of records per page |
Handles all information related with releases.
Allows action on the release collection.
| title | release title (starting by) |
|---|---|
| artist_id | artist id |
| artist_name | artist name (starting by) |
| label_id | label id |
| catalog_id | catalog id |
| from | release date string with format "yyyyMMdd" |
| to | release date string with format "yyyyMMdd" |
| page | page number |
| limit | maximum number of records per page |
Gets a given release profile.
Lists tracks from a given release.
| id | release id |
|---|---|
| artist_id | artist id |
| page | page number |
| limit | maximum number of records per page |
Handles all information related with tracks.
Allows action on the track collection.
| artist_id | artist id |
|---|---|
| release_id | release id |
| page | page number |
| limit | maximum number of records per page |
Gets a given track profile.
Lists all media items associated with the given track.
| id | track id |
|---|---|
| type | media item type
|
| format | media item format
|
| service | source service name, ex: ochre, youtube, etc... |
| catalog_id | catalog id |
| from | release date string with format "yyyyMMdd" |
| to | release date string with format "yyyyMMdd" |
| include_referen | sets if references are to be included in the response |
| page | page number |
| limit | maximum number of records per page |
Endpoint description
| reference_type | reference type
|
|---|---|
| reference_id | reference id |
| type | media item type
|
| format | media item format
|
| service | source service name, ex: ochre, youtube, etc... |
| catalog_id | catalog id |
| from | release date string with format "yyyyMMdd" |
| to | release date string with format "yyyyMMdd" |
| include_referen | sets if references are to be included in the response |
| page | page number |
| limit | maximum number of records per page |