Preparing your dataStory DesignerVisual design tips

Juicebox API

The Juicebox API can be used for generating urls to embed apps in your webpage.

Handling Pagination

The maximum pagination size is limited by object. Apps are limited to page sizes of 100, other objects will return 10000 objects. If the number of available objects exceeds the limit, the list will be paginated. Response headers will contain the following values.

  • X-Count The total number of objects available.

  • X-PageThe current page number

  • X-PageSize The number of objects on each page.

  • X-Next A link to fetch the next page of data. This will be "None" when on the last page of data.

  • X-Previous A link to fetch the previous page of data. This will be "None" when on the first page of data.

get

List Access Views

Authorizations
Responses
200Success
application/json
get
GET /api/v1/access_views/ HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*
200Success
[
  {
    "created": "2025-07-06T06:12:26.085Z",
    "modified": "2025-07-06T06:12:26.085Z",
    "key": "text",
    "is_active": true,
    "allowed_uses_cnt": 1,
    "usages_cnt": 1,
    "expires_at": "2025-07-06T06:12:26.085Z",
    "data_permissions": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "selections": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "show_header": true,
    "language_code": "text",
    "app": "text"
  }
]
post

List Access Views

Authorizations
Body
createdstring · date-timeRead-onlyRequired
modifiedstring · date-timeRead-onlyRequired
keystringRead-onlyRequired
is_activebooleanOptional

Can this access key be used

allowed_uses_cntinteger · min: -2147483648 · max: 2147483647Optional

The number of times this access key CAN BE used. 0=unlimited uses

usages_cntintegerRead-onlyRequired

The number of times this access key HAS BEEN used

expires_atstring · date-time | nullableOptional
show_headerbooleanOptional
language_codestring · max: 2Optional
appstringRequired

The app this key is granting access to

Responses
201Success
application/json
post
POST /api/v1/access_views/ HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 244

{
  "is_active": true,
  "allowed_uses_cnt": 1,
  "expires_at": "2025-07-06T06:12:26.085Z",
  "data_permissions": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "selections": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "show_header": true,
  "language_code": "text",
  "app": "text"
}
201Success
{
  "created": "2025-07-06T06:12:26.085Z",
  "modified": "2025-07-06T06:12:26.085Z",
  "key": "text",
  "is_active": true,
  "allowed_uses_cnt": 1,
  "usages_cnt": 1,
  "expires_at": "2025-07-06T06:12:26.085Z",
  "data_permissions": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "selections": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "show_header": true,
  "language_code": "text",
  "app": "text"
}
get

Get an Access View

Authorizations
Path parameters
keystringRequiredPattern: ^\w+$
Responses
200Success
application/json
get
GET /api/v1/access_views/{key}/ HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*
200Success
{
  "created": "2025-07-06T06:12:26.085Z",
  "modified": "2025-07-06T06:12:26.085Z",
  "key": "text",
  "is_active": true,
  "allowed_uses_cnt": 1,
  "usages_cnt": 1,
  "expires_at": "2025-07-06T06:12:26.085Z",
  "data_permissions": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "selections": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "show_header": true,
  "language_code": "text",
  "app": "text"
}
put

Modify an Access View

Authorizations
Path parameters
keystringRequiredPattern: ^\w+$
Body
createdstring · date-timeRead-onlyRequired
modifiedstring · date-timeRead-onlyRequired
keystringRead-onlyRequired
is_activebooleanOptional

Can this access key be used

allowed_uses_cntinteger · min: -2147483648 · max: 2147483647Optional

The number of times this access key CAN BE used. 0=unlimited uses

usages_cntintegerRead-onlyRequired

The number of times this access key HAS BEEN used

expires_atstring · date-time | nullableOptional
show_headerbooleanOptional
language_codestring · max: 2Optional
appstringRequired

The app this key is granting access to

Responses
200Success
application/json
put
PUT /api/v1/access_views/{key}/ HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 244

{
  "is_active": true,
  "allowed_uses_cnt": 1,
  "expires_at": "2025-07-06T06:12:26.085Z",
  "data_permissions": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "selections": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "show_header": true,
  "language_code": "text",
  "app": "text"
}
200Success
{
  "created": "2025-07-06T06:12:26.085Z",
  "modified": "2025-07-06T06:12:26.085Z",
  "key": "text",
  "is_active": true,
  "allowed_uses_cnt": 1,
  "usages_cnt": 1,
  "expires_at": "2025-07-06T06:12:26.085Z",
  "data_permissions": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "selections": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "show_header": true,
  "language_code": "text",
  "app": "text"
}
delete

Deleting an access view will set the is_active flag to False.

Authorizations
Path parameters
keystringRequiredPattern: ^\w+$
Responses
204
The access view has been set to inactive.
delete
DELETE /api/v1/access_views/{key}/ HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*
204

The access view has been set to inactive.

No content
patch

Modify an Access View

Authorizations
Path parameters
keystringRequiredPattern: ^\w+$
Body
createdstring · date-timeRead-onlyOptional
modifiedstring · date-timeRead-onlyOptional
keystringRead-onlyOptional
is_activebooleanOptional

Can this access key be used

allowed_uses_cntinteger · min: -2147483648 · max: 2147483647Optional

The number of times this access key CAN BE used. 0=unlimited uses

usages_cntintegerRead-onlyOptional

The number of times this access key HAS BEEN used

expires_atstring · date-time | nullableOptional
show_headerbooleanOptional
language_codestring · max: 2Optional
appstringOptional

The app this key is granting access to

Responses
200Success
application/json
patch
PATCH /api/v1/access_views/{key}/ HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 244

{
  "is_active": true,
  "allowed_uses_cnt": 1,
  "expires_at": "2025-07-06T06:12:26.085Z",
  "data_permissions": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "selections": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "show_header": true,
  "language_code": "text",
  "app": "text"
}
200Success
{
  "created": "2025-07-06T06:12:26.085Z",
  "modified": "2025-07-06T06:12:26.085Z",
  "key": "text",
  "is_active": true,
  "allowed_uses_cnt": 1,
  "usages_cnt": 1,
  "expires_at": "2025-07-06T06:12:26.085Z",
  "data_permissions": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "selections": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "show_header": true,
  "language_code": "text",
  "app": "text"
}
get

List Access Views

Authorizations
Path parameters
keystringRequiredPattern: ^\w+$
Responses
200Success
application/json
get
GET /api/v1/access_views/{key}/usage/ HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*
200Success
[
  {
    "data_permissions": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "selections": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "app_slug": "text",
    "show_header": true,
    "language_code": "text",
    "timestamp": "2025-07-06T06:12:26.085Z"
  }
]
post

For backward compatibility with some client's integrations that have hardcoded 200, we remap status 201 to 200.

Body

Serializer class used to validate a username and password.

'username' is identified by the custom UserModel.USERNAME_FIELD.

Returns a JSON Web Token that can be used to authenticate later calls.

passwordstringWrite-onlyRequired
tokenstringRead-onlyRequired
emailstringWrite-onlyRequired
Responses
200Success
application/json
post
POST /api/v1/jb/api-token-auth/ HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 34

{
  "password": "text",
  "email": "text"
}
200Success
{
  "token": "text"
}
get

Get a list of apps, new apps are created using the Juicebox editor.

Authorizations
Responses
200Success
application/json
get
GET /api/v1/jb/apps/ HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*
200Success
[
  {
    "client_id": "text",
    "created_at": "2025-07-06T06:12:26.085Z",
    "description": "text",
    "footer_html": "text",
    "help_html": "text",
    "id": "text",
    "in_maintenance": true,
    "invitation_body": "text",
    "invitation_subject": "text",
    "label": "text",
    "maintenance_message": "text",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "package_info": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "raw_config": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "show_footer": true,
    "show_help": true,
    "slug": "text",
    "usage": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "users": [
      1
    ]
  }
]
delete

Allow deleting redis cache for any app that the requesting user can modify.

Authorizations
Path parameters
idstringRequiredPattern: ^\w+(:\w+)?$
Responses
204
No response body
delete
DELETE /api/v1/jb/apps/{id}/clear_cache/ HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*
204

No response body

No content
PreviousJuicebox Embedding APINextRequesting data from embedded apps

Last updated

Was this helpful?