Score files against the scope's rules

Viewing v2— current version

POST

/v2/workspaces/{workspace_id}/scores

curl --request POST \
  --url https://api.app.layer.ai/api/v2/workspaces/:workspace_id/scores \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "file_ids": [
    "<uuid>"
  ],
  "project_id": "<uuid>",
  "rule_ids": [],
  "webhook": {
    "url": "<string>",
    "events": [
      "inference.completed"
    ],
    "metadata": {}
  }
}'

import requests

url = "https://api.app.layer.ai/api/v2/workspaces/:workspace_id/scores"

payload = {
    "file_ids": ["<uuid>"],
    "project_id": "<uuid>",
    "rule_ids": [],
    "webhook": {
        "url": "<string>",
        "events": ["inference.completed"],
        "metadata": {}
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

const url = 'https://api.app.layer.ai/api/v2/workspaces/:workspace_id/scores';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"file_ids":["<uuid>"],"project_id":"<uuid>","rule_ids":[],"webhook":{"url":"<string>","events":["inference.completed"],"metadata":{}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "https://api.app.layer.ai/api/v2/workspaces/:workspace_id/scores"

  payload := strings.NewReader("{\n  \"file_ids\": [\n    \"<uuid>\"\n  ],\n  \"project_id\": \"<uuid>\",\n  \"rule_ids\": [],\n  \"webhook\": {\n    \"url\": \"<string>\",\n    \"events\": [\n      \"inference.completed\"\n    ],\n    \"metadata\": {}\n  }\n}")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Authorization", "Bearer <token>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.app.layer.ai/api/v2/workspaces/:workspace_id/scores",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'file_ids' => [
        '<uuid>'
    ],
    'project_id' => '<uuid>',
    'rule_ids' => [

    ],
    'webhook' => [
        'url' => '<string>',
        'events' => [
                'inference.completed'
        ],
        'metadata' => [

        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"file_ids\": [\n    \"<uuid>\"\n  ],\n  \"project_id\": \"<uuid>\",\n  \"rule_ids\": [],\n  \"webhook\": {\n    \"url\": \"<string>\",\n    \"events\": [\n      \"inference.completed\"\n    ],\n    \"metadata\": {}\n  }\n}");
Request request = new Request.Builder()
  .url("https://api.app.layer.ai/api/v2/workspaces/:workspace_id/scores")
  .post(body)
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

require 'uri'
require 'net/http'

url = URI("https://api.app.layer.ai/api/v2/workspaces/:workspace_id/scores")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"file_ids\": [\n    \"<uuid>\"\n  ],\n  \"project_id\": \"<uuid>\",\n  \"rule_ids\": [],\n  \"webhook\": {\n    \"url\": \"<string>\",\n    \"events\": [\n      \"inference.completed\"\n    ],\n    \"metadata\": {}\n  }\n}"

response = http.request(request)
puts response.read_body

var client = new RestClient("https://api.app.layer.ai/api/v2/workspaces/:workspace_id/scores");
var request = new RestRequest("", Method.Post);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"file_ids\": [\n    \"<uuid>\"\n  ],\n  \"project_id\": \"<uuid>\",\n  \"rule_ids\": [],\n  \"webhook\": {\n    \"url\": \"<string>\",\n    \"events\": [\n      \"inference.completed\"\n    ],\n    \"metadata\": {}\n  }\n}", ParameterType.RequestBody);
var response = client.Execute(request);

Unchanged from v1. This endpoint’s documented request and response schemas are identical in v1 and v2 — change the /v1 prefix to /v2. Schema equality is not a promise about behaviour, so keep your usual smoke tests.

Queue scoring of up to 100 files against the output scoring rules in force.

Accepted and asynchronous: every (file, rule) pair is a vision-model call that spends Creative Units, and the verdicts land over the following seconds to minutes. Poll GET /v1/workspaces/{workspace_id}/files/{file_id}/scores for the results.

Scoring a file again is allowed and appends a fresh verdict rather than replacing the previous one. A scope with no rules in force queues nothing and reports zero pairs.

Authorizations

bearerAuth
oauth2
serviceAccount
projects:write

Parameters

Path Parameters

workspace_id

required

Workspace Id

Id of the workspace that owns the resource.

string format: uuid

Id of the workspace that owns the resource.

Header Parameters

Idempotency-Key

string

<= 255 characters

Opaque key making a retry of this request return the first result. A 2xx response is replayed for 24 hours with Idempotent-Replayed: true. A 4xx releases the key. A 5xx, or a request still running, holds the key for 120 seconds, during which a retry gets 409; after that a retry executes again. The key covers the method, path, query, and byte-identical body it was first used with; reusing it for a different request is rejected with 422. Protection is best effort: if the key store is unavailable, or a record is lost early, a retry can execute again even after an earlier 409. See the Idempotency section of the API description.

Request Body^required

application/json

ScoreFilesBody

object

file_ids

required

File Ids

The files to score. Images, video and 3D can be judged; audio and text cannot.

Array<string>

>= 1 items <= 100 items

project_id

Project Id

Score under a project’s policy as well as the workspace’s. A project’s rules are added to its workspace’s, never replace them.

string format: uuid

nullable

rule_ids

Rule Ids

Score against these rules only. Empty runs every rule in force for the scope.

Array<string>

default:

webhook

Any of:

WebhookInput
null

WebhookInput

Where to POST this request’s terminal events, and what to include with them.

object

url

required

Url

HTTPS URL that receives a POST when this request reaches a terminal state. Must be publicly reachable; must not redirect. Acknowledge with any 2xx within 10 seconds and do the work asynchronously. Reply 410 to stop delivery permanently.

string

<= 2048 characters

events

Events

Narrows what is delivered. Omit to receive every event this request can produce, which is what expected_events on the response lists.

Array<string>

nullable

Allowed values: inference.completed inference.failed inference.cancelled training.succeeded training.failed scoring_run.completed scoring_run.failed workflow_run.succeeded workflow_run.failed workflow_run.cancelled

metadata

Metadata

Opaque key/value pairs echoed back verbatim in every delivery, for correlating a callback with your own records. At most 10 keys and 1024 bytes in total.

object

key

additional properties

string

Responses

202

Successful Response

application/json

ScoreFilesOutput

object

scoring_run_id

Scoring Run Id

Handle for this batch. Poll GET /v1/workspaces/{workspace_id}/scoring-runs/{id} for its verdicts. Null when no rule was in force, which queues nothing.

string format: uuid

nullable

requested_pair_count

required

Requested Pair Count

How many (file, rule) judgements were queued — one model call each.

integer

file_count

required

File Count

How many files were accepted for scoring.

integer

rule_ids

required

Rule Ids

The rules the files are being scored against.

Array<string>

expected_events

Expected Events

Deliveries this run will produce. Empty when no webhook was supplied.

Array<string>

default:

Example

{
  "expected_events": []
}

401

Unauthenticated — missing or invalid Bearer token.

application/problem+json

object

type

required

string

title

required

string

status

required

integer

detail

required

string

Example

{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description."
}

403

Forbidden — insufficient permissions, or the access token lacks the scope the operation requires.

application/problem+json

object

type

required

string

title

required

string

status

required

integer

detail

required

string

Example

{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description."
}

404

Resource not found.

application/problem+json

object

type

required

string

title

required

string

status

required

integer

detail

required

string

Example

{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description."
}

409

The outcome of the request with this Idempotency-Key is not known yet: it is still running, or it failed without a stored response. Retry after the number of seconds in Retry-After.

application/problem+json

object

type

required

string

title

required

string

status

required

integer

detail

required

string

Example

{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description."
}

422

Invalid input parameters, or an Idempotency-Key reused for a different request.

application/problem+json

object

type

required

string

title

required

string

status

required

integer

detail

required

string

Example

{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description."
}

429

Rate limited — retry after the number of seconds in Retry-After.

application/problem+json

object

type

required

string

title

required

string

status

required

integer

detail

required

string

Example

{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description."
}

500

Internal server error.

application/problem+json

object

type

required

string

title

required

string

status

required

integer

detail

required

string

Example

{
  "type": "https://api.layer.ai/errors/ERROR_CODE",
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable description."
}

Score files against the scope's rules

Authorizations

Parameters

Path Parameters

Header Parameters

Request Bodyrequired

Responses

202

Example

401

Example

403

Example

404

Example

409

Example

422

Example

429

Example

500

Example

Request Body^required