Ochre General API

Ricardo Pinto ochreapi
Help

Apiary Powered Documentation

Sign in with Apiary account.

Ochre General API

Introduction

This document will expose all information related with all resources and actions.

Resource access

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.

  • Authorization: Bearer [access_token]

Sample call flow

Fetch a new access token

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

Call an API endpoint

curl -X GET \
  https://api.ochre.io/v1/music/artists \
  -H 'Authorization: Bearer [stored from previous ochre auth call]' \
  -H 'Host: api.ochre.io'

Style guide

  • resources - [api domain]/homepage/stores/{id}/[sub resources]

  • url style - spinal-case ex: [api domain]/player/products/{id}/sub-resources

  • json properties style - camelCase

Verbs

  • POST = create

  • GET = Read

  • PUT = Update/Replace

  • PATCH = Update/Modify

  • DELETE = Delete

Status codes

Custom headers

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)

Images

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.

  • Sizes
    • XL
      • value: xl
      • width: 2000
    • L
      • value: l
      • width: 1000
    • M
      • value: m
      • width: 500
    • XS
      • value: s
      • width: 250
    • XS
      • value: xs
      • width: 125
    • XXS
      • value: xxs
      • width: 80

Sample request: /music/releases/96596?image_size=m

This will return the artwork as a 500x500 image

Reference

CMS / Spaces


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.

Collection

Allows actions on the spaces collection.

Search

URI Parameters
name

space name (starting by)

type

space type

  • artist

  • release

  • label

  • store

  • generic (default)

owner_idowner id
owner_nameowner name
pagepage number
limitmaximum number of records per page.

Profile

Allows actions on a specific space.

Get

Navigation items

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.

List

URI Parameters
idspace id
pagepage number
limitmaximum number of records per page.
group_idnavigation group id

Views

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.

List

URI Parameters
idspace id
type

view type

  • artist

  • release

  • homepage

  • article

reference_type

reference type

  • artist

  • release

  • label

  • store

reference_idreference id
slugview slug
title

view title (starting by)

pagepage number
limitmaximum number of records per page

CMS / Views


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.

Collection

Allows actions on the view collection. As a GET request it will only allow to filter by one reference.

Search

URI Parameters
space_idspace id
type

view type

  • artist

  • release

  • homepage

  • article

reference_type

reference type

  • artist

  • release

  • label

  • store

reference_idreference id
slugview slug
title

view title (starting by)

pagepage number
limitmaximum number of records per page

Profile

Allows actions on a specific view.

Get

Modules

Lists all modules associated with the given view. This endpoint allows all module collection filters apart from view_id.

List

URI Parameters
idpage id
title

module title (starting by)

type

module type

  • product-block

  • list

  • text

  • image

  • video

  • banner

  • header

pagepage number
limitmaximum number of records per page

CMS / Modules


The category will allow to search modules, get a specific module profile as well as the inner items.

Collection

Allows action on the module collection.

Search

URI Parameters
view_idview id
title

module title (starting by)

type

module type Modules available are:

  • product-block

  • list

  • text

  • image

  • video

  • banner

  • header

pagepage number
limitmaximum number of records per page

Profile

Gets a module profile

Get

Content items

Lists content items associated with the given module

List

URI Parameters
id
pagepage number
limitmaximum number of records per page

Retail / Stores


This category exposes the store resource. It will allow searching stores and getting the related sub-resources.

Collection

Allows actions on the store collection.

Search

URI Parameters
pagepage number
limitmaximum number of records per page

Profile

Gets a store profile.

Get

Retail / Products


This category allows exposing all product related data. It's possible search products, get a product profile and its sub-resources.

Collection

Allows actions on the product collection.

Search

URI Parameters
store_idfilter by matching store
catalog_idrestrict by the main catalog id
group_idallows grouping results by product group id
variant_group_idallows grouping results by variant group id
title

filter product title (starting by)

type

filter by type

  • release

  • track

  • other

reference_type

reference type

  • artist

  • release

  • track

  • label

reference_idreference id
from

date string with format "yyyyMMdd"

to

date string with format "yyyyMMdd"

format

format title, ex: "vinyl", "mp3", "cd"

universe

universe name

  • music

  • clothing

  • merch

distribution

distribution type

  • physical

  • digital

variant

product variant name (mainly for clothing), ex: xs, s, l, xl, ...

allow_preordershow products based on their preorder permissions
pagepage number
limitmaximum number of records per page

Profile

Gets a given product resource.

Get

Availability

Check for the given product stock and territory availability. This will gather the location data from the request by ip or custom location headers.

Get

Bundle items

Lists all inner products included on for a given bundle product.

List

URI Parameters
idproduct id
pagepage number
limitmaximum number of records per page

Retail / Carts


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.

Collection

Allows actions on the cart collection.

Add

Creates a new cart resource.

URI Parameters
store_idstore id

Profile

Gets a specific cart profile. Carts will include an estimated postage cost associated.

Get

Items

Allows action on the items that belong to a given cart.

List

URI Parameters
idcart id
pagepage number
limitmaximum number of records per page

Add

Item profile

Allows actions on a specific cart item. Discounts will be calculated taking in consideration the vouchers that may be associated with the cart.

Get

Update

When accepted the full updated resource will be returned. Only quantities may be updated.

URI Parameters
idcart id
item_idcart item id

Delete

Vouchers

Allows actions on the voucher list that belong to the given cart.

List

URI Parameters
idcart id
pagepage number
limitmaximum number of records per page

Retail / Orders


Collection

Allows access to a filterable order collection. Results will be pulled from all catalogs to which the token has access to.

Search

URI Parameters
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)

  • format: yyyyMMdd
created_to

Limit date created (excluding)

  • format: yyyyMMdd
updated_from

Initial date updated to filter from (including)

  • format: yyyyMMdd
updated_to

Initial date created (excluding)

  • format: yyyyMMdd
total_min

Initial value to filter from (including)

total_max

Limit value to filter to (including)

pagepage number
limitmaximum number of records per page

Profile

Gets the order main object based on the id specified.

Get

Items

Allows access to the order item collection that belong to the specified order id.

List

The purchase order id will be inferred based on the URI so the order level related filters will be restricted will be ignored.

URI Parameters
id
created_from

Initial date created to filter from (including)

  • format: yyyyMMdd
created_to

Limit date created (excluding)

  • format: yyyyMMdd
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)

pagePage number
limitMaximum number of records per page

Retail / Order Items


Collection

Allows access to a filterable order item collection. Results will be pulled from all catalogs to which the token has access to.

Search

URI Parameters
store_ids

List of store ids split by ,

user_ids

List of user ids (customer ids) split by ,

order_idPurchase order id
order_numberPurchase order number string
created_from

Initial date created to filter from (including)

  • format: yyyyMMdd
created_to

Limit date created (excluding)

  • format: yyyyMMdd
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)

pagepage number
limitmaximum number of records per page

Profile

Gets the order item main object based on the id specified.

Get

Music / Labels


Handles all label related data.

Collection

Allows action on the label collection.

Search

URI Parameters
pagepage number
limitmaximum number of records per page

Profile

Gets a label profile.

Get

Music / Artists


Handles all information related with artists

Collection

Allows actions on the artist collection.

Search

URI Parameters
name

artist name (contains criteria)

active

artist status

  • true

  • false

catalog_idmain catalog id
pagepage number
limitmaximum number of records per page

Profile

Gets an artist profile.

Get

Releases

Lists releases from the given artist.

List

URI Parameters
idartist id
title

release title (starting by)

label_idlabel id
catalog_idcatalog id
from

release date string with format "yyyyMMdd"

to

release date string with format "yyyyMMdd"

pagepage number
limitmaximum number of records per page

Tracks

Lists tracks from the given artist.

List

URI Parameters
idartist id
release_idrelease id
pagepage number
limitmaximum number of records per page

Music / Releases


Handles all information related with releases.

Collection

Allows action on the release collection.

Search

URI Parameters
title

release title (starting by)

artist_idartist id
artist_name

artist name (starting by)

label_idlabel id
catalog_idcatalog id
from

release date string with format "yyyyMMdd"

to

release date string with format "yyyyMMdd"

pagepage number
limitmaximum number of records per page

Profile

Gets a given release profile.

Get

Tracks

Lists tracks from a given release.

List

URI Parameters
idrelease id
artist_idartist id
pagepage number
limitmaximum number of records per page

Music / Tracks


Handles all information related with tracks.

Collection

Allows action on the track collection.

Search

URI Parameters
artist_idartist id
release_idrelease id
pagepage number
limitmaximum number of records per page

Profile

Gets a given track profile.

Get

Media items

Lists all media items associated with the given track.

List

URI Parameters
idtrack id
type

media item type

  • audio

  • video

  • image

format

media item format

  • mp3

  • external_id

  • link

  • embed

service

source service name, ex: ochre, youtube, etc...

catalog_idcatalog id
from

release date string with format "yyyyMMdd"

to

release date string with format "yyyyMMdd"

include_referencessets if references are to be included in the response
pagepage number
limitmaximum number of records per page

Content / Media items


Endpoint description

Collection

Search

URI Parameters
reference_type

reference type

  • artist

  • release

  • track

  • product

  • product_group

reference_idreference id
type

media item type

  • audio

  • video

  • image

format

media item format

  • mp3

  • external_id

  • link

  • embed

service

source service name, ex: ochre, youtube, etc...

catalog_idcatalog id
from

release date string with format "yyyyMMdd"

to

release date string with format "yyyyMMdd"

include_referencessets if references are to be included in the response
pagepage number
limitmaximum number of records per page

Profile

Get