API¶

Authentication¶

All authentication is performed using JSON Web Tokens (RFC 7519) which must be signed using the HS256, HS384 or HS512 algorithm with the secret key.

Two system-level keys will be provided: one for production and one for staging environments. With these keys, you can manage users and devices from your back-end services. Do not use these keys outside of your trusted network.

In order to invoke facial recognition directly from installed tablets, you must register each device within the system, have a device-level key generated for it, and use it to sign all JWTs. If a tablet gets stolen, only one key will become compromised, just to be immediately revoked without affecting the rest of the system.

Each JWT must contain the kid field with the corresponding key ID, the sub field with your customer handle, and the aud field which must match the Host header of the HTTP request. Both iat and exp fields of the JWT must be present, with the difference of an hour or less (we recommend using short expiration periods of a few minutes) between the two.

Headers¶

Each request must contain a valid Authorization header with the Bearer authentication scheme and a Base64Url-encoded JWT (RFC 4648).

All POST, PUT, and PATCH requests must contain a valid Content-Type header whose value must match the media type of the contents.

Any request may contain a Request-Id header. In that case, the corresponding response will include the same header with the same identifier to help you with logging, tracing, or debugging.

Errors¶

Melon uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 200-299 range indicate success. The following are the codes used to indicate an error:

All 400-499 error responses may contain a JSON payload that carries a unique error identifier and an accompanying human readable message. The identifiers are stable and can be compared. The messages are for convenience only and can change at any time without warning.

Example error response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
"error": "BAD_AUTH",
"reason": "Token has expired"
}

Error response fields:

Below is the list of all possible error identifiers:

Endpoints¶

GET /v3/users¶

List users.

Example request:

GET /v3/users?page=5 HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>

Request parameters:

Example response:

HTTP/1.1 200 OK
Link: <.../v3/users?page=1>; rel="first"
Link: <.../v3/users?page=4>; rel="prev"
Link: <.../v3/users?page=6>; rel="next"
Link: <.../v3/users?page=100>; rel="last"
Content-Type: application/json

{
"page": 5,
"users": [
"0190ed21-8928-72d0-a9b9-22b91dcaa09a",
"0190ed21-8928-7e3c-b6dc-d8ffd7df4972",
"0190ed21-8928-7fa8-ba0f-b0f35d7d209a",
...
]
}

Response fields:

POST /v3/users¶

Create a user.

Example request:

POST /v3/users HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>
Content-Type: application/json

{
"display_name": "John Smith"
}

Request fields:

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
"uuid": "0190ed33-2084-76c8-8222-142040abd5f7",
"created": 1721966500,
"updated": 1721966500,
"display_name": "John Smith"
}

Response fields:

GET /v3/users/{user}¶

Retrieve a user.

Example request:

GET /v3/users/0190ed33-2084-76c8-8222-142040abd5f7 HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"uuid": "0190ed33-2084-76c8-8222-142040abd5f7",
"created": 1721966500,
"updated": 1721966500,
"display_name": "John Smith"
}

Response fields:

PATCH /v3/users/{user}¶

Update a user using the JSON Merge Patch (RFC 7396) algorithm.

Example request:

PATCH /v3/users/0190ed33-2084-76c8-8222-142040abd5f7 HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>
Content-Type: application/merge-patch+json

{
"display_name": "John David Smith"
}

Request fields:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"uuid": "0190ed33-2084-76c8-8222-142040abd5f7",
"created": 1721966500,
"updated": 1721969841,
"display_name": "John David Smith"
}

Response fields:

DELETE /v3/users/{user}¶

Delete a user.

Example request:

DELETE /v3/users/0190ed33-2084-76c8-8222-142040abd5f7 HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>

Example response:

HTTP/1.1 204 No Content

GET /v3/users/{user}/face¶

Retrieve a user's face metadata.

Example request:

GET /v3/users/0190ed33-2084-7d2e-bf87-7d5cc593334a/face HTTP/1.1
Host: api.melon.co.jp

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"created": 1721060244,
"updated": 1721060244
}

Response fields:

PUT /v3/users/{user}/face¶

Register a user face using JPEG or PNG images.

Example request:

PUT /v3/users/0190ed33-2084-7d2e-bf87-7d5cc593334a/face HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=XXX

--XXX
Content-Disposition: form-data; name="file"; filename="000001.png"
Content-Type: image/png

<binary data>
--XXX--

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"created": 1721154075,
"updated": 1729469136
}

Response fields:

DELETE /v3/users/{user}/face¶

Delete a user face.

Example request:

DELETE /v3/users/0190ed33-2084-7d2e-bf87-7d5cc593334a/face HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>

Example response:

HTTP/1.1 204 No Content

GET /v3/users/{user}/tokens¶

List user tokens.

Example request:

GET /v3/users/0190ed6c-0c07-7734-aa87-aa8bac04482f/tokens?page=5 HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>

Request parameters:

Example response:

HTTP/1.1 200 OK
Link: <.../tokens?page=1>; rel="first"
Link: <.../tokens?page=4>; rel="prev"
Link: <.../tokens?page=6>; rel="next"
Link: <.../tokens?page=10>; rel="last"
Content-Type: application/json

{
"page": 5,
"tokens": [
"0190ed6d-f8a9-7fd4-910f-cd54d46a43c3",
"0190ed6d-f8a9-7782-8cee-c98691cf2721",
"0190ed6d-f8a9-7a01-bbd5-e3260967eac7",
...
]
}

Response fields:

POST /v3/users/{user}/tokens¶

Create a user token.

Example request:

POST /v3/users/0190ed6c-0c07-7734-aa87-aa8bac04482f/tokens HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>
Content-Type: application/json

{
"valid_from": 1722178800,
"valid_through": 1722265199,
"metadata": {
"gallery": "NAGANO"
}
}

Request fields:

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
"uuid": "0190eda8-8a07-7507-aa9a-2303eed178cf",
"created": 1722104303,
"updated": 1722104303,
"valid_from": 1722178800,
"valid_through": 1722265199,
"metadata": {
"gallery": "NAGANO"
}
}

Response fields:

GET /v3/users/{user}/tokens/{token}¶

Retrieve a user token.

Example request:

GET /v3/users/0190ed6c-0c07-7734-aa87-aa8bac04482f/↵
tokens/0190eda8-8a07-7507-aa9a-2303eed178cf HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"uuid": "0190eda8-8a07-7507-aa9a-2303eed178cf",
"created": 1722104303,
"updated": 1722104303,
"valid_from": 1722178800,
"valid_through": 1722265199,
"metadata": {
"gallery": "NAGANO"
}
}

Response fields:

PATCH /v3/users/{user}/tokens/{token}¶

Update a user token using the JSON Merge Patch (RFC 7396) algorithm.

Example request:

PATCH /v3/users/0190ed6c-0c07-7734-aa87-aa8bac04482f/↵
tokens/0190eda8-8a07-7507-aa9a-2303eed178cf HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>
Content-Type: application/merge-patch+json

{
"valid_from": 1722265200,
"valid_through": 1722351599,
}

Request fields:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"uuid": "0190eda8-8a07-7507-aa9a-2303eed178cf",
"created": 1722104303,
"updated": 1722109648,
"valid_from": 1722265200,
"valid_until": 1722351599,
"metadata": {
"gallery": "NAGANO"
}
}

Response fields:

DELETE /v3/users/{user}/tokens/{token}¶

Delete a user token.

Example request:

DELETE /v3/users/0190ed6c-0c07-7734-aa87-aa8bac04482f/↵
tokens/0190eda8-8a07-7507-aa9a-2303eed178cf HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>

Example response:

HTTP/1.1 204 No Content

GET /v3/devices¶

List devices.

Example request:

GET v3/devices?page=5 HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>

Request parameters:

Example response:

HTTP/1.1 200 OK
Link: <.../v3/devices?page=1>; rel="first"
Link: <.../v3/devices?page=4>; rel="prev"
Link: <.../v3/devices?page=6>; rel="next"
Link: <.../v3/devices?page=10>; rel="last"
Content-Type: application/json

{
"page": 5,
"devices": [
"0190ed7a-33fa-79a4-9640-f6ad49c72212",
"0190ed7a-33fa-7f7a-92d2-3def7bb82c2b",
"0190ed7a-33fa-7c9e-a293-9aebb362615f",
...
]
}

Response fields:

POST /v3/devices¶

Create a device.

Example request:

POST /v3/devices HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>
Content-Type: application/json

{
"display_name": "a5c17z.ishikawa.garden.local",
"metadata": {
"gallery": "ISHIKAWA_1"
}
}

Request fields:

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
"uuid": "0190ed85-5efa-70eb-84f0-144016696248",
"created": 1721971875,
"updated": 1721971875,
"display_name": "a5c17z.ishikawa.garden.local",
"metadata": {
"gallery": "ISHIKAWA_1"
}
}

Response fields:

GET /v3/devices/{device}¶

Retrieve a device.

Example request:

GET /v3/devices/0190ed85-5efa-70eb-84f0-144016696248 HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"uuid": "0190ed85-5efa-70eb-84f0-144016696248",
"created": 1721971875,
"updated": 1721971875,
"display_name": "a5c17z.ishikawa.garden.local",
"metadata": {
"gallery": "ISHIKAWA_1"
}
}

Response fields:

PATCH /v3/devices/{device}¶

Update a device using the JSON Merge Patch (RFC 7396) algorithm.

Example request:

PATCH /v3/users/0190ed85-5efa-70eb-84f0-144016696248 HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>
Content-Type: application/merge-patch+json

{
"metadata": {
"gallery": "ISHIKAWA_2"
}
}

Request fields:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"uuid": "0190ed85-5efa-70eb-84f0-144016696248",
"created": 1721971875,
"updated": 1721971875,
"display_name": "a5c17z.ishikawa.garden.local",
"metadata": {
"gallery": "ISHIKAWA_2"
}
}

Response fields:

DELETE /v3/devices/{device}¶

Delete a device.

Example request:

DELETE /v3/devices/0190ed85-5efa-70eb-84f0-144016696248 HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>

Example response:

HTTP/1.1 204 No Content

GET /v3/devices/{device}/keys¶

List device keys.

Example request:

GET /v3/devices/0190ed85-5efa-7d65-b6b3-ea4cec1cb560/keys HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>

Request parameters:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"page": 1,
"keys": [
"0190ed8d-295d-70f6-ad6f-a30a12f4cde4"
]
}

Response fields:

POST /v3/devices/{device}/keys¶

Create a device key.

Example request:

POST /v3/devices/0190ed85-5efa-7d65-b6b3-ea4cec1cb560/keys HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
"uuid": "0190ed93-f885-7648-bddf-687fdbf5bf0e",
"created": 1721972898,
"secret": "<base64 data>"
}

Response fields:

GET /v3/devices/{device}/keys/{key}¶

Retrieve a device key.

Example request:

GET /v3/devices/0190ed85-5efa-7d65-b6b3-ea4cec1cb560/↵
keys/0190ed93-f885-7648-bddf-687fdbf5bf0 HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"uuid": "0190ed93-f885-7648-bddf-687fdbf5bf0e",
"created": 1721972898,
"secret": "<base64 data>"
}

Response fields:

DELETE /v3/devices/{device}/keys/{key}¶

Delete a device key.

Example request:

DELETE /v3/devices/0190ed85-5efa-7d65-b6b3-ea4cec1cb560/↵
keys/0190ed93-f885-7648-bddf-687fdbf5bf0 HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>

Example response:

HTTP/1.1 204 No Content

GET /v3/models¶

List feature detectors and facial recognition models.

Example request:

GET /v3/models HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>

Request parameters:

Example response:

HTTP/1.1 200 OK
Link: <.../models?page=1>; rel="first"
Link: <.../models?page=4>; rel="prev"
Link: <.../models?page=6>; rel="next"
Link: <.../models?page=10>; rel="last"
Content-Type: application/json

{
"page": 5,
"models": [
"unified_quality_score_24M",
"unified_quality_score_43M",
"unified_quality_score_100M",
...
]
}

Response fields:

GET /v3/models/{model}¶

Retrieve model metadata.

Example request:

GET /v3/models/face_detector_5M HTTP/1.1
Host: api.melon.co.jp

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"name: "face_detector_5M",
"description": "A face detector model (5M parameters)",
"parameters": [
{
"name": "revision",
"description": "Model revision",
"type": "string",
"enum": ["599a31a", "latest"],
"default": "latest"
},
...
]
}

Response fields:

POST /v3/models/{model}¶

Execute a model on a sequence of images.

Example request:

POST /v3/models/liveness_50M HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=XXX

--XXX
Content-Disposition: form-data; name="file"; filename="000001.jpg"
Content-Type: image/jpeg

<binary data>
--XXX--

A model can receive a number of request parameters, the names and types of which can be inspected through the GET endpoint.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
...
}

GET /v3/pipelines¶

List pipelines.

Example request:

GET v3/pipelines?page=5 HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>

Request parameters:

Example response:

HTTP/1.1 200 OK
Link: <.../v3/pipelines?page=1>; rel="first"
Link: <.../v3/pipelines?page=4>; rel="prev"
Link: <.../v3/pipelines?page=6>; rel="next"
Link: <.../v3/pipelines?page=10>; rel="last"
Content-Type: application/json

{
"page": 5,
"pipelines": [
"0198ea19-211d-7cca-9927-ad6c7626fefa",
"0198ea19-576b-7852-80bf-c78395b0b653",
"0198ea19-7f27-7194-b6a4-77efa47db16e",
...
]
}

Response fields:

POST /v3/pipelines¶

Create a pipeline.

Example request:

POST /v3/pipelines HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>
Content-Type: text/javascript

async (api, body, params) => {
return api.post('/v3/models/liveness_50M', body, params);
}

A pipeline is a JavaScript snippet that must define an anonymous async closure accepting 3 parameters, typically called api, body, and params.

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
"uuid": "0198ea24-06ff-7d47-a75b-75bbc4db6ddc",
"created": 1756275096,
"updated": 1756275096
}

Response fields:

GET /v3/pipelines/{pipeline}¶

Retrieve a pipeline.

Example request:

GET /v3/devices/0198ea24-06ff-7d47-a75b-75bbc4db6ddc HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>

Example response:

HTTP/1.1 200 OK
Content-Type: text/javascript

// Created: 2025-08-27T06:11:36+00:00
// Updated: 2025-08-27T06:11:36+00:00

async (api, body, params) => {
return api.post('/v3/models/liveness_50M', body);
}

PUT /v3/pipelines/{pipeline}¶

Update a pipeline.

Example request:

PUT /v3/pipelines/0198ea24-06ff-7d47-a75b-75bbc4db6ddc HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>
Content-Type: text/javascript

async (api, body, params) => {
return api.post('/v3/models/liveness_50M', body, {revision: 'c439865'});
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"uuid": "0198ea24-06ff-7d47-a75b-75bbc4db6ddc",
"created": 1756275096,
"updated": 1756275395
}

Response fields:

DELETE /v3/pipelines/{pipeline}¶

Delete a pipeline.

Example request:

DELETE /v3/pipelines/0198ea24-06ff-7d47-a75b-75bbc4db6ddc HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>

Example response:

HTTP/1.1 204 No Content

POST /v3/pipelines/{pipeline}¶

Execute a pipeline on a sequence of images.

Example request:

POST /v3/pipelines/identify HTTP/1.1
Host: api.melon.co.jp
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=XXX

--XXX
Content-Disposition: form-data; name="file"; filename="000001.jpg"
Content-Type: image/jpeg

<binary data>
--XXX--

A pipeline can receive a number of request parameters, all of which will be passed as its third parameter.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
...
}

Built-in pipelines¶

enroll_face¶

Enrolls a user's face in the system after performing all checks (image quality, liveness etc.)

Example request:

POST /v3/pipelines/enroll_face?user_id=0190fcef-d905-702e-8492-936bca2df6ff
Host: api.melon.co.jp
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=XXX

--XXX
Content-Disposition: form-data; name="file"; filename="000001.jpg"
Content-Type: image/jpeg

<binary data>
--XXX--

Request fields:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"created": 1721154075,
"updated": 1729469136
}

identify¶

Identify a user using a sequence of images.

Example request:

POST /v3/pipelines/identify
Host: api.melon.co.jp
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=XXX

--XXX
Content-Disposition: form-data; name="file"; filename="000001.png"
Content-Type: image/png

--XXX
Content-Disposition: form-data; name="file"; filename="000002.png"
Content-Type: image/png

<binary data>
--XXX--

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"users": [
{
"uuid": "0190fcef-d905-702e-8492-936bca2df6ff",
"score": 0.85
},
...
]
}

Response fields:

verify¶

Verify a user using a JPEG, JPEG 2000, or PNG image. Note: no liveness or cross check is run on the submitted ID image.

Example request:

POST /v3/pipelines/verify?user_id=0190ed21-8928-72d0-a9b9-22b91dcaa09a
Host: api.melon.co.jp
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=XXX

--XXX
Content-Disposition: form-data; name="file"; filename="000001.jp2"
Content-Type: image/jp2

<binary data>
--XXX--

Request fields:

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"score": 0.85
}

Response fields: