Grand Shooting API Documentation API Reference

Welcome to Grand Shooting API documentation.

You will find here information on how you can use our different REST endpoints to access and process your data from Grand Shooting.

API Endpoint
https://api-13.grand-shooting.com/v2
Contact: help@grand-shooting.com
Schemes: https
Version: 2.0.0

Authentication

Bearer

You can obtain a token from Grand Shooting administration pages.

You can use it by sending the header "Authorization" with value "Bearer (your token)"

type
apiKey
name
Authorization
in
header

Handle HTTP status

We respect HTTP standard and REST architecture.

Most of cases you will receive a success response contained in this table:

HTTP code Description
102 PENDING. The request is threated and takes some time.
200 OK, The request is threated with success.
201 Created, The request is threated with success and a content is created (e.g. for a POST request)
204 No Content, The request is threated with success but return no content in the response.

Please refer to the following table for identify your problem if you receive an HTTP error:

HTTP code Description
400 Bad request, in the response, you will see which field is missing or invalid.
401 Unauthorized, check if you passed the Authorization Header
404 Not found, the ressource is missing (e.g A user who have been deleted)
405 Method not allowed, the server know the endpoint used but don't permit this method
500 Internal server error, bad news it seems we have a problem

If you have an unidentified response, don't hesitate to contact our support.

Now you are be able to request all of our endpoints.

Rate limiting

Rate limiting is on account basis, or more accurately described, per authentication key. There is a limit on the number of simultaneous requests: you can call up to 5 requests per second.

When you exceed this rate limit for any endpoint of our API, the API will return a HTTP 429 “Too Many Requests” response code, and the following error will be returned in the response body:

{ "errors": [ { "message": "Rate limit exceeded" } ] }

The model

If you start coding with our API, you may be interested in having a first global overview of the main concepts behind Grand Shooting.

Note: The platform supports images and videos. This documentation is equally applicable to both and we may use indifferently the two words (images or videos). So, keep in mind that when we describe a feature, it is always applicable to both images and videos.

Productions and Benches

A production is a bunch of images that is processed according to a declared workflow. Every step of the workflow is called a bench.

A classic production is composed of 3 benches:

  1. Capture (corresponds to the “LIVE” feature of the web application)
  2. Retouching (often called “Phase 1”)
  3. Exports (see below) / Validation

You can have 2 retouching benches within the same production. It can be useful for instance if you want a first stage to clean up images with basic operations then a second stage with more in-depth retouching.

Retouching is optional: you can create a production with no retouching bench. On the contrary Capture, Exports and Validation are mandatory.

Be careful: you can update benches and delete retouching benches as long as no files has been loaded. If you delete a bench that contains files, they will be immediately deleted, and you won’t have the possibility to recover them.

To distinguish the benches within a production, the API includes a parameter called benchsetptype wich can take these values:

  • 10 – Capture
  • 20 – Retouching (phase 1)
  • 30 – Retouching (phase 2)
  • 40 – Exports / Validation

Exports and Validation

Exports refers to a specific bench of the production: the one before the validation bench.

The way you interact with images inside export and validation benches differs from the interactions within the first benches of the production: you load images to capture and retouching benches, but you just trigger exports to process retouched images. And the processed images are automatically dropped to the validation bench.

So, you never load images either to export benches nor to validation benches.

Be careful: don’t delete retouching benches if they already contain files. Otherwise you would not be able to trigger exports for this production anymore and you would have to start again with a new production.

Templates

Using the web application, you can create new productions from scratch then set up all the parameters by hand: the number of benches, user accesses on every bench, the settings for the export bench, and so on.

It doesn’t really have sense to give this level of precision from our API because the purpose of the API is to automate repetitive workflows.

That’s why you first create templates with predefined settings from the web application. Then, from the API, you instance new productions giving in parameters the Id of the template.

Shooting methods

Photo shoot sessions can be differentiated thanks to shooting methods.

Basically, a shooting method represents a specific way to get pictures of products: it can be products wared on models or it can be still life. You may also use different shooting methods to distinguish photos produced with different machines or technologies.

Therefore, shooting methods give you full control on how you want to monitor the productions: they appear on almost all reports and you will be able to filter for the values they can take.

Note: if you have questions about the best shooting method values for your organization, feel free to ask the support team for advice.

Shooting methods are set up from the web application with admin credentials. From the API, you can list them.

The catalog and its references

It is one of the big features of Grand Shooting: every image or video can be linked to a catalog. Thus, you will be able to organize image production by product references.

There is only one catalog. But you can combine products from different brands within the same catalog. The attributes stored in Grand Shooting are quite classic:

  • Up to 3 levels of categories (univers, gamme, family)
  • Brand Model
  • reference (product_ref)
  • Color
  • Size
  • Description,
  • collection,
  • gender
  • SKU
  • EAN

Every item in the catalog is identified in Grand Shooting by another attribute called 'ref' (for product reference). This 'ref' attribute can be a unique id, but it is commonly generated from other attributes.

For example, in the ready to wear market we need to take pictures not only of all product models but also of all color declinations. Then the ref attribute will be constructed from the model reference attribute concatenated with the color attribute.

Example: Model: S18BOHEMIAN
Color: 110
Ref: SS18BOHEMIAN_110

Important: keep in mind that 'ref' values should be unique in the catalog and that they refer to the product that need to be taken in photo.

The 'EAN' attribute is usefull if the samples do have barcodes. In the web application, typing the ref attribute of a product or scanning is barcode is strictly the same. That’s why 'EAN' values should also be unique.

Note: even if the attribute’s name is 'EAN', you don’t have to comply with 'EAN' standard (we don’t check the parity byte)

Note: sometimes you have multiple sizes of the same product references and you don’t know in advance which samples will be shot. Then you don’t know which 'EAN' have to be stored in you catalog. Don’t worry we already faced this issue many times, the support team will help you to find the solution.

Shotlist : list of products to be shot

From Grand Shooting’s web application, the guidelines define per product category how many images are attempted and what are the technical specifications of these images (in terms of size, resolution, ICC profile, …).

Shotlists make an inventory of existing images for every product in your catalog. They explicit the status of the images in your workflow and reveal alerts if an image does not comply with the guidelines.

More generally shotlists can be seen as the cockpit where you can see the work in progress from the point of view of the catalog.

Looks : group of references visible on the same images

This feature is useful especially for the ready to ware market.

Imagine a model wearing clothes: shoes, a pant, a shirt, a coat, … All these clothes make something up called a look.

In this case the looks are mostly composed before starting the photo shoot session. That’s why it makes sense to link images directly to the look and not to product references.

Be careful: the name of the looks have be different of the names of product references in the catalog.

Getting started

Our first production

So, let’s start with the API. We will stay simple and create a basic production. To do this, simply send the following request:

With the body:

The 2 main parameters are 'shooting_method_id' and 'bench_template_id'. They refer to the shooting method and to the template. They are the only parameters that cannot be changed once the production is created.

We set a smalltext “'My first production'” that will be viewable on the web application as the title of the production.

The 'startdate' parameter gives information about the day the first images shall be uploaded to this production. Usually it is the date of the photo shoot session. The time zone is explicitly set.

'enddate', 'timezone' and 'tzoffset' are optional. In this example the parameters are set to a capture session starting at 7.00 am and ending at 4.00 pm. If omitted, the timezone is set to "Europe/Paris".

POST https://api-13.grand-shooting.com/v2/production

    {  
    "smalltext": "My first production",  
    "startdate": "2017-03-27T07:00:00.000Z",
    "enddate": "2017-03-27T16:00:00.000Z",
    "timezone": "Europe/Paris",
    "tzoffset": 60,
    "shooting_method_id": 1,  
    "bench_template_id": 1  
    }

List the benches of a production

Now to list all the productions call this request:

It will return an array with all the productions, like this one:

You can see that the previously created production contains 3 benches: Capture ('benchsteptype' = 10), Retouching ('benchsteptype' = 20) and validation ('benchsteptype' = 40).

Benches are chained:

  • The first bench of a production has no 'parent_id'.
  • The 'root_id' is the id of the first bench for all benches of the production.
  • From one bench to the next one you can see that the 'parent_id' changed.

Note : By convention, the 'smalltext' attribute of the first bench of a production is repeated for all benches ("My first production" in this example). Then, the specific name of a bench is set between parenthesis ("Retouching" and "Export" in this example). The first bench of a production can't have any specific name as it is always set as "Live".

If you want to list all productions but not all benches of production, you can filter the benches with null as parent_id.

GET /production

    [ 
        [
            {
            "smalltext": "My first production",
            "startdate": "2017-03-27T07:00:00.000Z",
            "enddate": null,
            "timezone": "Europe/Paris",
            "tzoffset": 60,
            "shooting_method_id": 1,
            "bench_id": 1,
            "parent_id": null,
            "root_id": 1,
            "benchsteptype": 10
            },
            {
            "smalltext": "My first production (Retouching)",
            "startdate": "2017-03-27T07:00:00.000Z",
            "enddate": null,
            "timezone": "Europe/Paris",
            "tzoffset": 60,
            "shooting_method_id": 1,
            "bench_id": 2,
            "parent_id": 1,
            "root_id": 1,
            "benchsteptype": 20
            },
            {
            "smalltext": "My first production (Export)",
            "startdate": "2017-03-27T07:00:00.000Z",
            "enddate": null,
            "timezone": "Europe/Paris",
            "tzoffset": 60,
            "shooting_method_id": 1,
            "bench_id": 3,
            "parent_id": 2,
            "root_id": 1,
            "benchsteptype": 40
            }
        ]
    ]

Load bench of a production

If you need the details about a specific bench, you can call this endpoint:

You will get just the bench:

GET /production/{bench_root_id}/bench/{bench_id}

{
"smalltext": "My first production (Export)",
"startdate": "2017-03-27T07:00:00.000Z",
"enddate": null,
"timezone": "Europe/Paris",
"tzoffset": 60,
"shooting_method_id": 1,
"bench_id": 3,
"parent_id": 2,
"root_id": 1,
"benchsteptype": 40
}

List the pictures of a bench

Once you created a production and you know there are some pictures, you may want to list them. Super easy, just send this request:

In this example we list images from the third bench. The body of the response is an array of picture objects like this one:

GET https://api-13.grand-shooting.com/v2/picture?bench_id=3

{
"picture_id": 3,
"bench_id": 3,
"bench_root_id": 1,
"ref": "3596654282833",
"path": "4c76bb10-d028-4988-b008-01a97c38a232/3596654282833_3.jpg",
"smalltext": "3596654282833_3.jpg",
"picturestatus": 50,
"filesize": 503637,
"reference_id": 1,
"child_ids": [],
"parent_id": 2
}

File name and path

Basically you can consider that a bench is a secured folder in which files are stored. Files can be organized in subfolders and the path attribute indicates the exact location of a file inside the bench.

So, there might be 2 images with the same filename "3596654282833_3.jpg" in this bench. But there can be just one image with this path ""4c76bb10-d028-4988-b008-01a97c38a232/3596654282833_3.jpg".

Picture status

'picturestatus' attribute refers to the status of an image (or video) inside a production. It can take one of these values :

HTTP code Description
5 RESHOOT, Image to be shot again.
10 NOT SELECTED, Image in the Live with default status
30 SELECTED, Image in the Live selected for retouching
31 REFUSED, Image refused, need some more work
35 REFUSED, Image refused by the retouchers
40 FOR APPROVAL, Image submitted for approval
50 VALIDATED, Image validated
52 ERROR, Error during the tranfer to the DAM
55 RELEASED, Image transferred to the DAM

Head's up ! : the status of a picture and the type of its bench are correlated. For instance a bench that corresponds to a Live ('benchsteptype' = 10) should only have pictures with status 5, 10 or 30. And a bench that corresponds to a validation step should only have pictures with status above than 40, except for the refused image ('picturestatus' = 31).

Note : Even if an image is not selected (in the Live bench), it can be retouched in the retouching benches then exported for approval. And of course a refused image can be retouched again and exported again for approval.

If Grand Shooting is integrated with a PIM, a DAM or Amazon S3, images will automatically take these status after having been transferred. In most cases, only validated images are transferred.

What is the difference between the 2 REFUSED status ? The common way to refuse an image is in the export bench : the status value of the image is 31. But an image can also be refused by a retoucher in the bench for retouching : in this case the status value is 35.

Upload images

We learned how to list the productions and their benches. Now let's try to upload images.

With a multipart body:

As you can see, it is very simple to integrate our API and manage image productions from your own applications: with few lines of code, you instantiate new productions then load / download images to / from the benches.

Keep in mind that the way you manage images within benches for capture and retouching differs from the interactions you can have with images within benches for export and validation.

POST /production/{bench_root_id}/bench/{bench_id}/upload

look

look

List looks

GET /look

Return looks

200 OK

Successful

type
object[]
Response Example (200 OK) 
[
  {
    "look_entry_id": 1,
    "look_id": 12,
    "ref": "FW19_ALDA_PINK",
    "rang": 10,
    "useforref": true,
    "look_smalltext": "LOOK_PE12"
  }
]
look

Create look

POST /look

Return nothing

picture_id: number

Name of look

look_smalltext: string

Name of look

data: object[]
object
look_entry_id: number x ≥ 1
look_id: number x ≥ 1
ref: string
rang: string
useforref: boolean
look_smalltext: string

Name of the look

Request Example
{
  "picture_id": "number",
  "look_smalltext": "string",
  "data": [
    {
      "look_entry_id": 1,
      "look_id": 12,
      "ref": "FW19_ALDA_PINK",
      "rang": 10,
      "useforref": true,
      "look_smalltext": "LOOK_PE12"
    }
  ]
}
default

Successful

type
string
Response Example (default ) 
"string"

picture

picture

List pictures

GET /picture

Return an array of pictures with a pagination of 100.

You can set the offset of pagination with the header 'offset'. Response headers:

  • 'X-Total-Count': Total number of items
  • 'X-Offset': Offset of the result
  • 'X-Count': Size of the result
offset: number x ≥ 0
in header

offset for pagination

picture_id: string
in query

id of the picture

bench_id: string
in query

id of the bench the picture belongs to

bench_root_id: string
in query

id of the bench the picture belongs to

benchsteptype: string
in query

Workflow step of production

ref: string
in query

ref extracted from picture

path: string
in query

path of the picture in the repository

smalltext: string
in query

picture filename

picturestatus: string
in query

Worlflow step of the picture. 5 : to reshoot 10 : not selected 30 : selected 31 : refused 35 : refused 40 : submited for approval 50 : validated 51 : ready to broadcast (in case of manual broadcast) 52 : error during broadcast 55 : broadcast (once validated a picture can be broadcast on ) 80 : archived

filesize: string
in query

filesize

width: string
in query

width

height: string
in query

height

reference_id: string
in query

undefined

reference_ids: string
in query

undefined

parent_id: string
in query

undefined

child_ids: string
in query

undefined

icc_profile: string
in query

path of the picture in the repository

thumbnail: string
in query

url of thumbnail

hash: string
in query

hash computed from image content

view_type_code: string
in query

view type code

transfert_date: string
in query

Transfert date of the picture (in Grand Shooting)

date_cre: string
in query

Creation date of the picture (in Grand Shooting)

validation_date: string
in query

Validation date

frame: string
in query

undefined

export: string
in query

name of the export

shootingmethod: string
in query

name of the shooting method

200 OK

Successful

type
object[]
Response Example (200 OK) 
[
  {
    "picture_id": 1023,
    "bench_id": 2,
    "bench_root_id": 1,
    "benchsteptype": 20,
    "ref": "FW19_ALDA_PINK",
    "path": "f33cdd25-b8b0-48dd-abac-cf8a29529f89/JPG/FW19_ALDA_PINK-1.jpg",
    "smalltext": "FW19_ALDA_PINK_1.jpg",
    "picturestatus": 30,
    "filesize": 520000,
    "reference_id": 10,
    "reference_ids": [
      12,
      140
    ],
    "parent_id": 151,
    "child_ids": [
      2034,
      1034
    ],
    "export": "WEB",
    "frame": {
      "x1": 1000,
      "y1": 1000,
      "x2": 2000,
      "y2": 4000
    },
    "icc_profile": "sRGB IEC61966-2.1",
    "thumbnail": "https://d2ui6hcz8iRm23.cdn.com/96/90/aca22fe007c.jpg",
    "hash": "5ef7fcb04a5c2e90a0f490e92a3260c50a259a5c",
    "shootingmethod": "Packshot"
  }
]
picture

Get picture

GET /picture/{picture_id}

Load a picture by its id

picture_id: number
in path

the id for the picture item

200 OK

Successful

type
object
Response Example (200 OK) 
{
  "picture_id": 1023,
  "bench_id": 2,
  "bench_root_id": 1,
  "benchsteptype": 20,
  "ref": "FW19_ALDA_PINK",
  "path": "f33cdd25-b8b0-48dd-abac-cf8a29529f89/JPG/FW19_ALDA_PINK-1.jpg",
  "smalltext": "FW19_ALDA_PINK_1.jpg",
  "picturestatus": 30,
  "filesize": 520000,
  "reference_id": 10,
  "reference_ids": [
    12,
    140
  ],
  "parent_id": 151,
  "child_ids": [
    2034,
    1034
  ],
  "export": "WEB",
  "frame": {
    "x1": 1000,
    "y1": 1000,
    "x2": 2000,
    "y2": 4000
  },
  "icc_profile": "sRGB IEC61966-2.1",
  "thumbnail": "https://d2ui6hcz8iRm23.cdn.com/96/90/aca22fe007c.jpg",
  "hash": "5ef7fcb04a5c2e90a0f490e92a3260c50a259a5c",
  "shootingmethod": "Packshot"
}
picture

Delete a picture

DELETE /picture/{picture_id}

Delete a picture from Grand Shooting (logicaly, file is prefixed with __TRASH and invisible in Grand Shooting). You can't delete a picture in validation stage (benchsteptype 40), you have to delete it through the export process.

picture_id: number
in path

the id for the picture item

default

Successful

type
string
Response Example (default ) 
"string"
picture

Download

GET /picture/{picture_id}/download

Download a picture

picture_id: number
in path

the id for the picture item

default

Successful

type
string
Response Example (default ) 
"string"
picture

Get tags

GET /picture/{picture_id}/tag

List picture tags.

Tagging information are extracted from picture metadata.

Color label and ratings are commonly used tagging information used in photo edition software like Photoshop, Capture One and Lightroom.

Other metadata are extracted from deep leaning categorisation models

picture_id: number
in path

the id for the picture item

200 OK

Successful

type
object
Response Example (200 OK) 
{
  "rating": 2,
  "label": "red",
  "tags": {
    "MODEL": true,
    "PACKSHOT": false,
    "RECO": true
  }
}
picture

Set tags

PUT /picture/{picture_id}/tag

Modify or add tagging information to pictures.

You can override color label or rating defined in picture EXIF metadata.

Picture's file internal EXIF metadata is not modified. New tag information will be available in Grand Shooting production filters

rating: number 0 ≤ x ≤ 5

rating of picture, between 0 and 5

label: string transparent, white, yellow, orange, red, pink, purple, blue, green

color tag of picture

tags: object
picture_id: number
in path

the id for the picture item

Request Example
{
  "rating": 2,
  "label": "red",
  "tags": {
    "MODEL": true,
    "PACKSHOT": false,
    "RECO": true
  }
}
200 OK

Successful

type
object
Response Example (200 OK) 
{
  "rating": 2,
  "label": "red",
  "tags": {
    "MODEL": true,
    "PACKSHOT": false,
    "RECO": true
  }
}
picture

Get specifications

GET /picture/{picture_id}/specification

Get specifications the picture should conform to

picture_id: number
in path

the picture id

default

Successful

type
string
Response Example (default ) 
"string"
picture

Set picturestatus

POST /picture/{picture_id}/picturestatus

Change picture status in the production workflow.

Depending on the woflow step (benchsteptype of the picture's bench), available status for pictures are different:

* Live: 5, 10, 30
* Phase 1: 30, 35
* Phase 2: 30, 35
* Valdation: 31, 40, 50, 51, 52, 55, 80
picturestatus: number

The new picture status

comment: string

Add comment with the status

picture_id: number
in path

The id for the picture item

Request Example
{
  "picturestatus": "number",
  "comment": "string"
}
200 OK

Success

type
string
400 Bad Request

Bad Request

404 Not Found

Picture not found

Response Example (200 OK) 
"string"
picture

Send picture to edit

POST /picture/edit/bulk

You can edit a picture only if an edit bench exist.

picture_ids: number[]

The id of pictures to edit

number
transfer_id: number

The id of FTP transfer

get_path: string

Set path to get picture from the FTP

put_path: string

Set path to put picture to FTP

provision_code: string

Set the edit code

account_id: number

Account id of picture to retouch

Request Example
{
  "picture_ids": [
    "number"
  ],
  "transfer_id": "number",
  "get_path": "string",
  "put_path": "string",
  "provision_code": "string",
  "account_id": "number"
}
200 OK

Success

type
string
400 Bad Request

Bad Request

404 Not Found

Picture not found

Response Example (200 OK) 
"string"
picture

Send picture to edit

POST /picture/{picture_id}/edit

You can edit a picture only if an edit bench exist.

transfer_id: number

The id of FTP transfer

get_path: string

Set path to get picture from the FTP

put_path: string

Set path to put picture to FTP

provision_code: string

Set the edit code

account_id: number

Account id of picture to retouch

picture_id: number
in path

The id for the picture item

Request Example
{
  "transfer_id": "number",
  "get_path": "string",
  "put_path": "string",
  "provision_code": "string",
  "account_id": "number"
}
200 OK

Success

type
string
400 Bad Request

Bad Request

404 Not Found

Picture not found

Response Example (200 OK) 
"string"
picture

Set a frame

PUT /picture/{picture_id}/frame

Set a frame on the image for custom processing (only for images, not yet for videos)

x1: number

start x pixel

y1: number

start y pixel

x2: number

end x pixel

y2: number

end y pixel

Request Example
{
  "x1": "number",
  "y1": "number",
  "x2": "number",
  "y2": "number"
}
default

Successful

type
string
Response Example (default ) 
"string"

production

production

List productions

GET /production

List all productions.

200 OK

Successful

type
object[][]
Response Example (200 OK) 
[
  [
    {
      "bench_id": 3,
      "parent_id": 2,
      "root_id": 1,
      "smalltext": "RTW_2019 DAY1 packshot",
      "startdate": "2018-12-25T22:45:00",
      "enddate": "2018-12-26T22:45:00",
      "timezone": "Europe/Paris",
      "tzoffset": 60,
      "shooting_method_id": 1,
      "benchsteptype": 40,
      "info": {
        "Photograph": "John Smith",
        "Model": "John Snow",
        "Stylist": "John Wick"
      },
      "info_model": [
        {
          "key": "Photograph",
          "label": "Photograph",
          "type": "text"
        },
        {
          "key": "Model",
          "label": "Model",
          "type": "text"
        },
        {
          "key": "stylist",
          "label": "Stylist",
          "type": "text"
        },
        {
          "key": "online_date",
          "label": "Online date",
          "type": "date"
        },
        {
          "key": "studio_number",
          "label": "Studio number",
          "type": "int"
        }
      ]
    }
  ]
]
production

Create production

POST /production

Create a production in which you can load images. A production is built on a workflow with different steps. Each step is a bench in which you can load images. If you wan't a specific workflow, you can apply a template. The default workflow is :

  • live (benchsteptype : 10)
  • post production step (benchsteptype : 20) optional
  • post production step (benchsteptype : 30) optional
  • export (benchsteptype : 40)
smalltext: string

Bench label

startdate: string (date)

Start date

enddate: string (date)

End date

timezone: string Europe/Paris

Timezone

tzoffset: number 60

Timezone offset in minutes

shooting_method_id: number x ≥ 1

Shooting method ID

bench_template_id: number x ≥ 1

Id of a template to configure bench

info: object
info_model: object[]

Description of what that can be stored in "info" field

object
key: string

used to identify column in import and export files

label: string

used for display in screens

type: string

the type of the column

Request Example
{
  "smalltext": "RTW_2019 DAY1 packshot",
  "startdate": "2018-12-25T22:45:00",
  "enddate": "2018-12-26T22:45:00",
  "timezone": "Europe/Paris",
  "tzoffset": 60,
  "shooting_method_id": 1,
  "bench_template_id": 1,
  "info": {
    "Photograph": "John Smith",
    "Model": "John Snow",
    "Stylist": "John Wick"
  },
  "info_model": [
    {
      "key": "Photograph",
      "label": "Photograph",
      "type": "text"
    },
    {
      "key": "Model",
      "label": "Model",
      "type": "text"
    },
    {
      "key": "stylist",
      "label": "Stylist",
      "type": "text"
    },
    {
      "key": "online_date",
      "label": "Online date",
      "type": "date"
    },
    {
      "key": "studio_number",
      "label": "Studio number",
      "type": "int"
    }
  ]
}
default

Successful

type
string
Response Example (default ) 
"string"
production

List templates

GET /production/template

List templates availables. They can be used during a production creation.

default

Successful

type
string
Response Example (default ) 
"string"
production

Get benches

GET /production/{bench_root_id}/bench

List benches in a production.

bench_root_id: number
in path

the production id

200 OK

Successful

type
object[]
Response Example (200 OK) 
[
  {
    "bench_id": 3,
    "parent_id": 2,
    "root_id": 1,
    "smalltext": "RTW_2019 DAY1 packshot",
    "startdate": "2018-12-25T22:45:00",
    "enddate": "2018-12-26T22:45:00",
    "timezone": "Europe/Paris",
    "tzoffset": 60,
    "shooting_method_id": 1,
    "benchsteptype": 40,
    "info": {
      "Photograph": "John Smith",
      "Model": "John Snow",
      "Stylist": "John Wick"
    },
    "info_model": [
      {
        "key": "Photograph",
        "label": "Photograph",
        "type": "text"
      },
      {
        "key": "Model",
        "label": "Model",
        "type": "text"
      },
      {
        "key": "stylist",
        "label": "Stylist",
        "type": "text"
      },
      {
        "key": "online_date",
        "label": "Online date",
        "type": "date"
      },
      {
        "key": "studio_number",
        "label": "Studio number",
        "type": "int"
      }
    ]
  }
]
production

Trigger export

GET /production/{bench_root_id}/startexport

Start an export, i.e. process automatic renaming and modifications on pictures to add them to validation step.

bench_root_id: number
in path

the production id

102

Export is already processing

200 OK

Success

type
string
400 Bad Request

Bad Request

404 Not Found

Bench not found

Response Example (200 OK) 
"string"
production

Get bench

GET /production/{bench_root_id}/bench/{bench_id}

Load a bench by its id

bench_id: number
in path

the bench id

bench_root_id: number
in path

the production id

200 OK

Successful

type
object
Response Example (200 OK) 
{
  "bench_id": 3,
  "parent_id": 2,
  "root_id": 1,
  "smalltext": "RTW_2019 DAY1 packshot",
  "startdate": "2018-12-25T22:45:00",
  "enddate": "2018-12-26T22:45:00",
  "timezone": "Europe/Paris",
  "tzoffset": 60,
  "shooting_method_id": 1,
  "benchsteptype": 40,
  "info": {
    "Photograph": "John Smith",
    "Model": "John Snow",
    "Stylist": "John Wick"
  },
  "info_model": [
    {
      "key": "Photograph",
      "label": "Photograph",
      "type": "text"
    },
    {
      "key": "Model",
      "label": "Model",
      "type": "text"
    },
    {
      "key": "stylist",
      "label": "Stylist",
      "type": "text"
    },
    {
      "key": "online_date",
      "label": "Online date",
      "type": "date"
    },
    {
      "key": "studio_number",
      "label": "Studio number",
      "type": "int"
    }
  ]
}
production

Add references

POST /production/{bench_root_id}/reference

Define wich references should be shot during a production.

object
bench_id: number
ref: string
Request Example
[
  {
    "bench_id": "number",
    "ref": "string"
  }
]
default

Successful

type
string
Response Example (default ) 
"string"
production

Upload pictures on a bench

POST /production/{bench_root_id}/bench/{bench_id}/upload

Return a status code

bench_root_id: number
in path

the production id

bench_id: number
in path

the bench id

file: file
in formData

picture file

wait: boolean true
in formData

wait end of upload to return

path: string /
in formData

path to upload picture

transfer_id: number
in formData

id of a transfer the files uploaded are linked to. Only for plugins purpose

200 OK

Success

type
string
400 Bad Request

Bad Request

Response Example (200 OK) 
"string"
production

Upload pictures on a bench by providing urls instead of files

POST /production/{bench_root_id}/bench/{bench_id}/upload/url

Return a status code

wait: boolean true

wait end of upload to return

path: string /

path to upload picture

urls: object[]

list of urls

object
url: string

url of picture to upload

filename: string

filename

transfer_id: number

id of a transfer the files uploaded are linked to. Only for plugins purpose

bench_root_id: number
in path

the production id

bench_id: number
in path

the bench id

Request Example
{
  "wait": "boolean",
  "path": "string",
  "urls": [
    {
      "url": "string",
      "filename": "string"
    }
  ],
  "transfer_id": "number"
}
default

Successful

type
string
Response Example (default ) 
"string"
production

Update production

PUT /production/{bench_root_id}

Update a production, basicaly to modify production's name and dates.

smalltext: string

Bench label

startdate: string (date)

Start date

enddate: string (date)

End date

timezone: string Europe/Paris

Timezone

tzoffset: number 60

Timezone offset in minutes

shooting_method_id: number x ≥ 1

Shooting method ID

bench_template_id: number x ≥ 1

Id of a template to configure bench

info: object
info_model: object[]

Description of what that can be stored in "info" field

object
key: string

used to identify column in import and export files

label: string

used for display in screens

type: string

the type of the column

bench_root_id: number
in path

the production id

Request Example
{
  "smalltext": "RTW_2019 DAY1 packshot",
  "startdate": "2018-12-25T22:45:00",
  "enddate": "2018-12-26T22:45:00",
  "timezone": "Europe/Paris",
  "tzoffset": 60,
  "shooting_method_id": 1,
  "bench_template_id": 1,
  "info": {
    "Photograph": "John Smith",
    "Model": "John Snow",
    "Stylist": "John Wick"
  },
  "info_model": [
    {
      "key": "Photograph",
      "label": "Photograph",
      "type": "text"
    },
    {
      "key": "Model",
      "label": "Model",
      "type": "text"
    },
    {
      "key": "stylist",
      "label": "Stylist",
      "type": "text"
    },
    {
      "key": "online_date",
      "label": "Online date",
      "type": "date"
    },
    {
      "key": "studio_number",
      "label": "Studio number",
      "type": "int"
    }
  ]
}
200 OK

Successful

type
object
Response Example (200 OK) 
{
  "bench_id": 3,
  "parent_id": 2,
  "root_id": 1,
  "smalltext": "RTW_2019 DAY1 packshot",
  "startdate": "2018-12-25T22:45:00",
  "enddate": "2018-12-26T22:45:00",
  "timezone": "Europe/Paris",
  "tzoffset": 60,
  "shooting_method_id": 1,
  "benchsteptype": 40,
  "info": {
    "Photograph": "John Smith",
    "Model": "John Snow",
    "Stylist": "John Wick"
  },
  "info_model": [
    {
      "key": "Photograph",
      "label": "Photograph",
      "type": "text"
    },
    {
      "key": "Model",
      "label": "Model",
      "type": "text"
    },
    {
      "key": "stylist",
      "label": "Stylist",
      "type": "text"
    },
    {
      "key": "online_date",
      "label": "Online date",
      "type": "date"
    },
    {
      "key": "studio_number",
      "label": "Studio number",
      "type": "int"
    }
  ]
}

reference

reference

List references

GET /reference

Return an array of references with a pagination of 100. You can set the offset of pagination with the header 'offset'. Response headers: 'X-Total-Count': Total number of items 'X-Offset': Offset of the result 'X-Count': Size of the result

200 OK

Successful

type
object[]
Response Example (200 OK) 
[
  {
    "reference_id": 12,
    "ref": "FW19_ALDA_PINK",
    "ean": "2309309834098",
    "eans": [
      "2309309834093",
      "2309309834091"
    ],
    "univers": "RTW",
    "gamme": "Accessories",
    "family": "Handbags",
    "sku": "EPOIAPOIJKLH109384",
    "brand": "BATCHEMON",
    "smalltext": "Pink leather handbag Alda",
    "product_ref": "FW19_ALDA",
    "product_smalltext": "Leather handbag Alda",
    "gender": "Woman",
    "color": "PINK",
    "hexa_color": "#FFC0CB",
    "size": "L",
    "collection": "FW19",
    "comment": "Closeup on zip",
    "tags": [
      "urgent",
      "leather"
    ],
    "online": "20/12/2019",
    "extra": {
      "composition": [
        "30% coton",
        "beef leather"
      ]
    }
  }
]
reference

Create / update a reference.

POST /reference

If a reference already exists with the same "ref", this reference will be updated. Otherwise, a new reference is created. Return the corresponding reference item with the generated id

reference_id: number x ≥ 1

id of the reference

ref: string

reference label identifier

ean: string

main ean

eans: string[]

alternatives ean

string
univers: string

univers, level 1 in catalog hierarchy

gamme: string

gamme, level 2 in catalog hierarchy

family: string

family, level 3 in catalog hierarchy

sku: string

sku

brand: string

brand

smalltext: string

reference label

product_ref: string

product identifier

product_smalltext: string

product label

gender: string

gender

gender_smalltext: string

gender

color: string

color

hexa_color: string

Code couleur RGB en hexa décimal

size: string

size

collection: string

collection

comment: string

comment

tags: string[]

tags

string
extra: object
shotlist_id: number x ≥ 1

id of a shotlist to add reference to

online: string

online date

Request Example
{
  "reference_id": 12,
  "ref": "FW19_ALDA_PINK",
  "ean": "2309309834098",
  "eans": [
    "2309309834093",
    "2309309834091"
  ],
  "univers": "RTW",
  "gamme": "Accessories",
  "family": "Handbags",
  "sku": "EPOIAPOIJKLH109384",
  "brand": "BATCHEMON",
  "smalltext": "Pink leather handbag Alda",
  "product_ref": "FW19_ALDA",
  "product_smalltext": "Leather handbag Alda",
  "gender": "Woman",
  "color": "PINK",
  "hexa_color": "#FFC0CB",
  "size": "L",
  "collection": "FW19",
  "comment": "Closeup on zip",
  "tags": [
    "urgent",
    "leather"
  ],
  "online": "20/12/2019",
  "extra": {
    "composition": [
      "30% coton",
      "beef leather"
    ]
  }
}
200 OK

Successful

type
object
Response Example (200 OK) 
{
  "reference_id": 12,
  "ref": "FW19_ALDA_PINK",
  "ean": "2309309834098",
  "eans": [
    "2309309834093",
    "2309309834091"
  ],
  "univers": "RTW",
  "gamme": "Accessories",
  "family": "Handbags",
  "sku": "EPOIAPOIJKLH109384",
  "brand": "BATCHEMON",
  "smalltext": "Pink leather handbag Alda",
  "product_ref": "FW19_ALDA",
  "product_smalltext": "Leather handbag Alda",
  "gender": "Woman",
  "color": "PINK",
  "hexa_color": "#FFC0CB",
  "size": "L",
  "collection": "FW19",
  "comment": "Closeup on zip",
  "tags": [
    "urgent",
    "leather"
  ],
  "online": "20/12/2019",
  "extra": {
    "composition": [
      "30% coton",
      "beef leather"
    ]
  }
}
reference

Get reference

GET /reference/{id}

Return a reference item

id: number
in path

the id for the reference item

200 OK

Successful

type
object
Response Example (200 OK) 
{
  "reference_id": 12,
  "ref": "FW19_ALDA_PINK",
  "ean": "2309309834098",
  "eans": [
    "2309309834093",
    "2309309834091"
  ],
  "univers": "RTW",
  "gamme": "Accessories",
  "family": "Handbags",
  "sku": "EPOIAPOIJKLH109384",
  "brand": "BATCHEMON",
  "smalltext": "Pink leather handbag Alda",
  "product_ref": "FW19_ALDA",
  "product_smalltext": "Leather handbag Alda",
  "gender": "Woman",
  "color": "PINK",
  "hexa_color": "#FFC0CB",
  "size": "L",
  "collection": "FW19",
  "comment": "Closeup on zip",
  "tags": [
    "urgent",
    "leather"
  ],
  "online": "20/12/2019",
  "extra": {
    "composition": [
      "30% coton",
      "beef leather"
    ]
  }
}
reference

Create / update multiple references

POST /reference/bulk

Returns the list of corresponding reference items

object
reference_id: number x ≥ 1

id of the reference

ref: string

reference label identifier

ean: string

main ean

eans: string[]

alternatives ean

string
univers: string

univers, level 1 in catalog hierarchy

gamme: string

gamme, level 2 in catalog hierarchy

family: string

family, level 3 in catalog hierarchy

sku: string

sku

brand: string

brand

smalltext: string

reference label

product_ref: string

product identifier

product_smalltext: string

product label

gender: string

gender

gender_smalltext: string

gender

color: string

color

hexa_color: string

Code couleur RGB en hexa décimal

size: string

size

collection: string

collection

comment: string

comment

tags: string[]

tags

string
extra: object
shotlist_id: number x ≥ 1

id of a shotlist to add reference to

online: string

online date

Request Example
[
  {
    "reference_id": 12,
    "ref": "FW19_ALDA_PINK",
    "ean": "2309309834098",
    "eans": [
      "2309309834093",
      "2309309834091"
    ],
    "univers": "RTW",
    "gamme": "Accessories",
    "family": "Handbags",
    "sku": "EPOIAPOIJKLH109384",
    "brand": "BATCHEMON",
    "smalltext": "Pink leather handbag Alda",
    "product_ref": "FW19_ALDA",
    "product_smalltext": "Leather handbag Alda",
    "gender": "Woman",
    "color": "PINK",
    "hexa_color": "#FFC0CB",
    "size": "L",
    "collection": "FW19",
    "comment": "Closeup on zip",
    "tags": [
      "urgent",
      "leather"
    ],
    "online": "20/12/2019",
    "extra": {
      "composition": [
        "30% coton",
        "beef leather"
      ]
    }
  }
]
200 OK

Successful

type
object[]
Response Example (200 OK) 
[
  {
    "reference_id": 12,
    "ref": "FW19_ALDA_PINK",
    "ean": "2309309834098",
    "eans": [
      "2309309834093",
      "2309309834091"
    ],
    "univers": "RTW",
    "gamme": "Accessories",
    "family": "Handbags",
    "sku": "EPOIAPOIJKLH109384",
    "brand": "BATCHEMON",
    "smalltext": "Pink leather handbag Alda",
    "product_ref": "FW19_ALDA",
    "product_smalltext": "Leather handbag Alda",
    "gender": "Woman",
    "color": "PINK",
    "hexa_color": "#FFC0CB",
    "size": "L",
    "collection": "FW19",
    "comment": "Closeup on zip",
    "tags": [
      "urgent",
      "leather"
    ],
    "online": "20/12/2019",
    "extra": {
      "composition": [
        "30% coton",
        "beef leather"
      ]
    }
  }
]
reference

Add / Modify column of extra field

POST /reference/column

Returns columns

object
key: string

used to identify column in import and export files

label: string

used for display in screens

type: string

the type of the column

Request Example
[
  {
    "key": "shopify-product_id",
    "label": "Shopify Product ID",
    "type": "int"
  }
]
default

Successful

type
string
Response Example (default ) 
"string"

shootingmethod

shootingmethod

List shooting methods

GET /shootingmethod

List all shooting methods

200 OK

Successful

type
object[]
Response Example (200 OK) 
[
  {
    "shooting_method_id": 10,
    "shootingmethod": "Packshot"
  }
]

stock

stock

Stock positions

GET /stock

List all stock information

default

Successful

type
string
Response Example (default ) 
"string"
stock

add to stock

POST /stock

Add a reference in stock

batch_id: number

batch id

reference_id: number

reference id

batchrefstatus: number

Status of the stock object

Request Example
{
  "batch_id": "number",
  "reference_id": "number",
  "batchrefstatus": "number"
}
default

Successful

type
string
Response Example (default ) 
"string"
stock

zones

GET /stock/zone

List zones

200 OK

Successful

type
object[]
Response Example (200 OK) 
[
  {
    "smalltext": "string"
  }
]
stock

Create a batch

POST /stock/batch

Create a batch

smalltext: string

Name of the batch

batch_type: number

Type of the batch

batch_zone_id: number

Zone where the batch is located

Request Example
{
  "smalltext": "string",
  "batch_type": "number",
  "batch_zone_id": "number"
}
default

Successful

type
string
Response Example (default ) 
"string"

webhook

webhook

List webhook

GET /webhook

Return webhook

200 OK

Successful

type
object[]
Response Example (200 OK) 
[
  {
    "address": "https://myapp.com/picture",
    "topic": "pictures/create",
    "webhook_id": 217894
  }
]
webhook

Create a webhook

POST /webhook

Return webhook

address: string

URI where the webhook subscription should send the POST request when the event occurs.

topic: string pictures/create, pictures/update

Event that triggers the webhook.

Request Example
{
  "address": "https://myapp.com/picture",
  "topic": "pictures/create"
}
200 OK

Successful

type
object
Response Example (200 OK) 
{
  "address": "https://myapp.com/picture",
  "topic": "pictures/create",
  "webhook_id": 217894
}
webhook

Create a webhook

PUT /webhook/{webhook_id}

Return webhook

address: string

URI where the webhook subscription should send the POST request when the event occurs.

topic: string pictures/create, pictures/update

Event that triggers the webhook.

Request Example
{
  "address": "https://myapp.com/picture",
  "topic": "pictures/create"
}
200 OK

Successful

type
object
Response Example (200 OK) 
{
  "address": "https://myapp.com/picture",
  "topic": "pictures/create",
  "webhook_id": 217894
}
webhook

Create a webhook

DELETE /webhook/{webhook_id}

Return webhook

default

Successful

type
string
Response Example (default ) 
"string"
Documentation by Spectacle