Productions

The first thing you do when you have registered your user, is to create or manage a Production. The production can be considered as the workspace you will operate in.

In the context of a production, you can:

Upload and search clips;
Organize your clips into collections and categories;
Manage the team that can access this material, with the ability to give each member a role, determining what they can do in the production;
Configure the metadata fields (Custom Fields / Form Fields);
Configure the workflows that should operate on your material;
And much more.

Limecraft also uses terminology such as Production Workspaces and Delivery Workspaces. As far as the usage of our API is concerned, the underlying objects for each of these concepts are still Productions, except that some of their configuration is different depending on the product use cases they support. Hence, in this developer documentation we stick to that term.

Listing productions

GET /production

This API call is used to list all productions user has access to.

Details

Description

List of ExtendedProduction objects is returned.

Parameters

✘

Return Type

ExtendedProduction

Field Name	Required	Type	Description	Format
accountId	✘	Long	The id of the account that holds this production	int64
accountName	✘	String	The name of the account that holds this production
accountUserId	✘	Long	The is of the user that is owner of the account that holds this production	int64
activeSecurityClasses	✘	Set of string		Enum:
activeStatus	✘	String		Enum: Active, Archived,
avatar	✘	Avatar
categories	✘	List of Category	The categories declared in this production
created	✘	Date	The time when this resource was created	date-time
createdBy	✘	String	The request or process that created this resource
creatorId	✘	Long	The id of the user who created this resource	int64
creatorName	✘	String	The creator of this production
deleted	✘	Date	When the production was deleted	date-time
deliveryDate	✘	Date		date-time
deliveryRequestFormFieldsDefinition	✘	FormFieldsDefinition
deliveryRequests	✘	List of DeliveryRequest
description	✘	String	The description of the production
editorialObjects	✘	List of EditorialObject
hasAvatar	✘	Boolean
id	✔	Long	The id of this resource	int64
invitationState	✘	String	The current state of the invitation that ties the current user to this production	Enum: PENDING, ACCEPTED, PENDING_AWAITING_2FA, ACCEPTED_AWAITING_2FA, EXPIRED,
invitations	✘	List of object	A list of invitations that were sent out in this production
lastActivity	✘	Date	The time in which the last activity was registered for this production	date-time
lastTouched	✘	Date	The time in which the last modify activity was registered for this production	date-time
lastUpdated	✘	Date	The time when this resource was last updated	date-time
modifiedBy	✔	String	The request or process responsible for the last update of this resource
name	✔	String	The name of the production
objectType	✘	String	The data model type or class name of this resource
participants	✘	Set of ExtendedUser	The team members of this production
producerId	✘	Long	The id of the account owner that holds this production	int64
producerName	✘	String	The name of the account owner that holds this production
productionFormFieldValues	✘	Object
productionFormFieldsDefinition	✘	FormFieldsDefinition
rights	✘	Set of string	The rights of the current user in this production
rolePresets	✘	Map of array	The role presets of this production
roles	✘	List of object	The roles that are declared in this production
serviceIntegrations	✘	List of ServiceIntegration	The service integrations that are declared in this production
settings	✘	ProductionSetting
sharedUsers	✘	List of SharedUser	The list of shared users in this production
subscription	✘	Subscription
subscriptionId	✘	Long	The id of the subscription where this production belongs to	int64
subscriptionStatus	✘	String	The status of the subscription where this production belongs to	Enum: trialing, trial_ended, assessing, active, soft_failure, past_due, suspended, canceled, unpaid, expired, delayed_cancel, unlinked,
subtitle	✘	String	A secondary title for the production
systemSettings	✘	SystemSetting
tentative	✘	Boolean	If the current user has not yet accepted the invitation to this production, this will be set to false
usages	✘	List of BillingUsage	The billing usages of this production
version	✔	Long	The version of this resource, used for Optimistic Locking	int64

Field Name

Required

Type

Description

Format

accountId

✘

Long

The id of the account that holds this production

int64

accountName

✘

String

The name of the account that holds this production

accountUserId

✘

Long

The is of the user that is owner of the account that holds this production

int64

activeSecurityClasses

✘

Set of string

Enum:

activeStatus

✘

String

Enum: Active, Archived,

avatar

✘

Avatar

Content Type

application/json

Responses

Table 1. http response codes
Code	Description	Datatype
200	The request was successful.	`ExtendedProduction`

The result is a list of Productions. This call implements the Paging, Sorting and Query interfaces for filtering lists of productions, as also discussed in detail below.

Filtering productions

Productions can be queried by means of filter query fq parameters (see Query Interface) of which the following are currently supported:

Query parameter Action Example

Query parameter	Action	Example
`id`	Return the production with the specified id.	`/api/production?fq=id:2431` or `/api/production?fq=id:(2431 2433)` if you wish to query for multiple values.
`name`	Filter by name.	`/api/production?fq=name:ProductionName1`
`type`	Type of workspace (e.g. `"DELIVERY"`)	Only Delivery Workspaces: `/api/production?fq=type:DELIVERY` Only Production Workspaces (easiest way is to simply exclude Delivery Workspaces): `/api/production?fq=-type:DELIVERY`
`created`	Filter by a time range in which the production was created.	`/api/production?fq=created:[2013-07-17T00:00:00Z TO 2023-07-17T00:00:00Z]`
`lastActivity`	Filter by a time range in which the production was last visited.	`/api/production?fq=lastActivity:[2013-07-17T00:00:00Z TO 2023-07-17T00:00:00Z]`
`lastTouched`	Filter by a time range in which the production was last edited (e.g.: added clips, collections, …).	`/api/production?fq=lastActivity:[2013-07-17T00:00:00Z TO 2023-07-17T00:00:00Z]`
`settings.<X>`	Filter by production setting <X>.	Only simple queries are supported here (e.g: `settings.enableArchive:true`). Furthermore, only the root properties of the settings can be used in queries. So, something like `settings.root.nested.property:SomeValue` is not supported yet.
`accountId`	Filter productions that belong to a given account.	`/api/production?fq=accountId:344` or `/api/production?fq=accountId:(344 863)` if you wish to query for multiple values.
`subscriptionId`	Filter productions that belong to a given subscription.	`/api/production?fq=subscriptionId:344` or `/api/production?fq=subscriptionId:(344 863)` if you wish to query for multiple values.

id

Return the production with the specified id.

/api/production?fq=id:2431 or /api/production?fq=id:(2431 2433) if you wish to query for multiple values.

name

Filter by name.

/api/production?fq=name:ProductionName1

type

Type of workspace (e.g. "DELIVERY")

Only Delivery Workspaces: /api/production?fq=type:DELIVERY
Only Production Workspaces (easiest way is to simply exclude Delivery Workspaces): /api/production?fq=-type:DELIVERY

created

Filter by a time range in which the production was created.

/api/production?fq=created:[2013-07-17T00:00:00Z TO 2023-07-17T00:00:00Z]

lastActivity

Filter by a time range in which the production was last visited.

/api/production?fq=lastActivity:[2013-07-17T00:00:00Z TO 2023-07-17T00:00:00Z]

lastTouched

Filter by a time range in which the production was last edited (e.g.: added clips, collections, …).

/api/production?fq=lastActivity:[2013-07-17T00:00:00Z TO 2023-07-17T00:00:00Z]

settings.<X>

Filter by production setting <X>.

Only simple queries are supported here (e.g: settings.enableArchive:true).
Furthermore, only the root properties of the settings can be used in queries.
So, something like settings.root.nested.property:SomeValue is not supported yet.

accountId

Filter productions that belong to a given account.

/api/production?fq=accountId:344 or /api/production?fq=accountId:(344 863) if you wish to query for multiple values.

subscriptionId

Filter productions that belong to a given subscription.

/api/production?fq=subscriptionId:344 or /api/production?fq=subscriptionId:(344 863) if you wish to query for multiple values.

Example

The following example makes use of some filters from the table above, combining them with partial matching.

GET /api/production?fq=name:My Produ*&fq=settings.myProductionSetting:MyValu*

It means that all productions whose name starts with My Produ, and have a setting named myProductionSetting with value that starts with MyValu will be matched.

Example

The following example makes use of some filters from the table above, combining them with partial matching.

GET /api/production?fq=name:My Produ*&fq=settings.myProductionSetting:MyValu*

It means that all productions whose name starts with My Produ, and have a setting named myProductionSetting with value that starts with MyValu will be matched.

Getting a single production

You can obtain a specific production by issuing GET call with the production id as an url path parameter.

GET /production/{id}

This API call is used to retrieve a specific production based on it’s id.

Details

Description

At most one production object is returned.

Parameters

Path Parameters

Name Description Required Type

Name	Description	Required	Type
`id`	ID of the production.	✔	Long

id

ID of the production.

✔

Long

Return Type

Production

Field Name	Required	Type	Description	Format
activeSecurityClasses	✘	Set of string		Enum:
activeStatus	✘	String		Enum: Active, Archived,
created	✘	Date	The time when this resource was created	date-time
createdBy	✘	String	The request or process that created this resource
creatorId	✘	Long	The id of the user who created this resource	int64
deleted	✘	Date	When the production was deleted	date-time
deliveryDate	✘	Date		date-time
deliveryRequestFormFieldsDefinition	✘	FormFieldsDefinition
deliveryRequests	✘	List of DeliveryRequest
description	✘	String	The description of the production
editorialObjects	✘	List of EditorialObject
hasAvatar	✘	Boolean
id	✔	Long	The id of this resource	int64
invitationState	✘	String	The current state of the invitation that ties the current user to this production	Enum: PENDING, ACCEPTED, PENDING_AWAITING_2FA, ACCEPTED_AWAITING_2FA, EXPIRED,
lastActivity	✘	Date	The time in which the last activity was registered for this production	date-time
lastTouched	✘	Date	The time in which the last modify activity was registered for this production	date-time
lastUpdated	✘	Date	The time when this resource was last updated	date-time
modifiedBy	✔	String	The request or process responsible for the last update of this resource
name	✔	String	The name of the production
objectType	✘	String	The data model type or class name of this resource
productionFormFieldValues	✘	Object
productionFormFieldsDefinition	✘	FormFieldsDefinition
serviceIntegrations	✘	List of ServiceIntegration	The service integrations that are declared in this production
settings	✘	ProductionSetting
subscription	✘	Subscription
subscriptionId	✘	Long	The id of the subscription where this production belongs to	int64
subscriptionStatus	✘	String	The status of the subscription where this production belongs to	Enum: trialing, trial_ended, assessing, active, soft_failure, past_due, suspended, canceled, unpaid, expired, delayed_cancel, unlinked,
subtitle	✘	String	A secondary title for the production
systemSettings	✘	SystemSetting
tentative	✘	Boolean	If the current user has not yet accepted the invitation to this production, this will be set to false
usages	✘	List of BillingUsage	The billing usages of this production
version	✔	Long	The version of this resource, used for Optimistic Locking	int64

Field Name

Required

Type

Description

Format

activeSecurityClasses

✘

Set of string

Enum:

activeStatus

✘

String

Enum: Active, Archived,

created

✘

Date

The time when this resource was created

date-time

createdBy

✘

String

The request or process that created this resource

creatorId

✘

Long

The id of the user who created this resource

int64

deleted

✘

Date

When the production was deleted

date-time

deliveryDate

✘

Date

date-time

deliveryRequestFormFieldsDefinition

✘

FormFieldsDefinition

deliveryRequests

✘

List of DeliveryRequest

description

✘

String

The description of the production

editorialObjects

✘

List of EditorialObject

hasAvatar

✘

Boolean

✔

Long

The id of this resource

int64

invitationState

✘

String

The current state of the invitation that ties the current user to this production

Enum: PENDING, ACCEPTED, PENDING_AWAITING_2FA, ACCEPTED_AWAITING_2FA, EXPIRED,

lastActivity

✘

Date

The time in which the last activity was registered for this production

date-time

lastTouched

✘

Date

The time in which the last modify activity was registered for this production

date-time

lastUpdated

✘

Date

The time when this resource was last updated

date-time

modifiedBy

✔

String

The request or process responsible for the last update of this resource

name

✔

String

The name of the production

objectType

✘

String

The data model type or class name of this resource

productionFormFieldValues

✘

Object

productionFormFieldsDefinition

✘

FormFieldsDefinition

serviceIntegrations

✘

List of ServiceIntegration

The service integrations that are declared in this production

settings

✘

ProductionSetting

subscription

✘

Subscription

subscriptionId

✘

Long

The id of the subscription where this production belongs to

int64

subscriptionStatus

✘

String

The status of the subscription where this production belongs to

Enum: trialing, trial_ended, assessing, active, soft_failure, past_due, suspended, canceled, unpaid, expired, delayed_cancel, unlinked,

subtitle

✘

String

A secondary title for the production

systemSettings

✘

SystemSetting

tentative

✘

Boolean

If the current user has not yet accepted the invitation to this production, this will be set to false

usages

✘

List of BillingUsage

The billing usages of this production

version

✔

Long

The version of this resource, used for Optimistic Locking

int64

Content Type

application/json

Responses

Table 2. http response codes
Code	Description	Datatype
200	The request was successful.	`Production`
403	Unsuccessful attempt due to the user not having PRODUCTION_VIEW rights.	`ForbiddenError`

Example response

After making a successful GET request to a specific production, you should receive a response similar to the one below:

{
    "id": 2433,
    "created": 1651148021466,
    "createdBy": "REST",
    "creatorId": 3274,
    "creatorName": "The Creator",
    "href": "https://platform.limecraft.com/api/production/123456789",
    "invitationState": "ACCEPTED",
    "lastActivity": 1678268909403,
    "lastTouched": 1678268909403,
    "lastUpdated": 1651148021824,
    "metricInstances": null,
    "name": "AwesomeProductionName",
    "objectType": "ExtendedProduction",
    "participants": [],
    "producerId": 3274,
    "producerName": "The Producer",
    "public": false,
    "rights": [],
    "status": "NORMAL",
    "subscriptionId": 599,
    "tentative": false,
    "type": "FICTION",
    "version": 2
}

Include parameters

The production resulting from a GET call can be enriched with additional properties to prevent repeating a query for each production separately. The following include parameters are supported within a call that returns a production:

Query parameter Action

Query parameter	Action
`includeRoles`	Include the production roles
`includeRoleRights`	Include the role rights when returning roles
`includeParticipants`	Include the production team members
`includeAccount`	Include the account details of the production
`includeRolePresets`	Include the role presets of the production
`includeRights`	Include the rights of the current user
`includeInvitations`	Include the production invitation
`includeTentative`	Include the team members that have not yet accepted their invitation
`includeAvatar`	Include the Avatar (or screenshot) of the production
`includeUsages`	Include the billing usage of the production
`includeSettings`	Include the settings of the production
`includeCategories`	Include the categories of the production
`includeSharedUsers`	Include the shared users of the production. These are users that have access to a shared collection in the production.

includeRoles

Include the production roles

includeRoleRights

Include the role rights when returning roles

includeParticipants

Include the production team members

includeAccount

Include the account details of the production

includeRolePresets

Include the role presets of the production

includeRights

Include the rights of the current user

includeInvitations

Include the production invitation

includeTentative

Include the team members that have not yet accepted their invitation

includeAvatar

Include the Avatar (or screenshot) of the production

includeUsages

Include the billing usage of the production

includeSettings

Include the settings of the production

includeCategories

Include the categories of the production

includeSharedUsers

Include the shared users of the production. These are users that have access to a shared collection in the production.

Although using include flags seems very convenient to load a lot of information in one go, developers must be careful when using them. Each include flag will increase the response size and time, so use only those elements that are strictly needed.

Example

GET /api/production/{id}?includeTentative=true&includeRights=true&includeParticipants=true