Check Artifact

POST

api

artifact

cURL

curl --request POST \
  --url https://eu.whitecircle.com/api/artifact \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'whitecircle-version: <whitecircle-version>' \
  --data '
{
  "content": {
    "kind": "<string>",
    "data": "<string>",
    "mime_type": "<string>",
    "name": "<string>",
    "url": "<string>"
  },
  "deployment_id": "<string>",
  "external_artifact_id": "<string>",
  "external_session_id": "<string>",
  "internal_session_id": "<string>",
  "metadata": {},
  "role": "<string>",
  "span_id": "<string>",
  "trace_id": "<string>"
}
'

import requests

url = "https://eu.whitecircle.com/api/artifact"

payload = {
    "content": {
        "kind": "<string>",
        "data": "<string>",
        "mime_type": "<string>",
        "name": "<string>",
        "url": "<string>"
    },
    "deployment_id": "<string>",
    "external_artifact_id": "<string>",
    "external_session_id": "<string>",
    "internal_session_id": "<string>",
    "metadata": {},
    "role": "<string>",
    "span_id": "<string>",
    "trace_id": "<string>"
}
headers = {
    "whitecircle-version": "<whitecircle-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'whitecircle-version': '<whitecircle-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    content: {
      kind: '<string>',
      data: '<string>',
      mime_type: '<string>',
      name: '<string>',
      url: '<string>'
    },
    deployment_id: '<string>',
    external_artifact_id: '<string>',
    external_session_id: '<string>',
    internal_session_id: '<string>',
    metadata: {},
    role: '<string>',
    span_id: '<string>',
    trace_id: '<string>'
  })
};

fetch('https://eu.whitecircle.com/api/artifact', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://eu.whitecircle.com/api/artifact",
  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([
    'content' => [
        'kind' => '<string>',
        'data' => '<string>',
        'mime_type' => '<string>',
        'name' => '<string>',
        'url' => '<string>'
    ],
    'deployment_id' => '<string>',
    'external_artifact_id' => '<string>',
    'external_session_id' => '<string>',
    'internal_session_id' => '<string>',
    'metadata' => [
        
    ],
    'role' => '<string>',
    'span_id' => '<string>',
    'trace_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "whitecircle-version: <whitecircle-version>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://eu.whitecircle.com/api/artifact"

	payload := strings.NewReader("{\n  \"content\": {\n    \"kind\": \"<string>\",\n    \"data\": \"<string>\",\n    \"mime_type\": \"<string>\",\n    \"name\": \"<string>\",\n    \"url\": \"<string>\"\n  },\n  \"deployment_id\": \"<string>\",\n  \"external_artifact_id\": \"<string>\",\n  \"external_session_id\": \"<string>\",\n  \"internal_session_id\": \"<string>\",\n  \"metadata\": {},\n  \"role\": \"<string>\",\n  \"span_id\": \"<string>\",\n  \"trace_id\": \"<string>\"\n}")

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

	req.Header.Add("whitecircle-version", "<whitecircle-version>")
	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(string(body))

}

HttpResponse<String> response = Unirest.post("https://eu.whitecircle.com/api/artifact")
  .header("whitecircle-version", "<whitecircle-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"content\": {\n    \"kind\": \"<string>\",\n    \"data\": \"<string>\",\n    \"mime_type\": \"<string>\",\n    \"name\": \"<string>\",\n    \"url\": \"<string>\"\n  },\n  \"deployment_id\": \"<string>\",\n  \"external_artifact_id\": \"<string>\",\n  \"external_session_id\": \"<string>\",\n  \"internal_session_id\": \"<string>\",\n  \"metadata\": {},\n  \"role\": \"<string>\",\n  \"span_id\": \"<string>\",\n  \"trace_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://eu.whitecircle.com/api/artifact")

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

request = Net::HTTP::Post.new(url)
request["whitecircle-version"] = '<whitecircle-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"content\": {\n    \"kind\": \"<string>\",\n    \"data\": \"<string>\",\n    \"mime_type\": \"<string>\",\n    \"name\": \"<string>\",\n    \"url\": \"<string>\"\n  },\n  \"deployment_id\": \"<string>\",\n  \"external_artifact_id\": \"<string>\",\n  \"external_session_id\": \"<string>\",\n  \"internal_session_id\": \"<string>\",\n  \"metadata\": {},\n  \"role\": \"<string>\",\n  \"span_id\": \"<string>\",\n  \"trace_id\": \"<string>\"\n}"

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

{
  "policies": {},
  "kind": "<string>",
  "status": "<string>",
  "internal_artifact_id": "<string>",
  "flagged": true,
  "updated_at": "<string>",
  "external_artifact_id": "<string>",
  "external_session_id": "<string>",
  "internal_session_id": "<string>",
  "created_at": "<string>",
  "note": "<string>"
}

Check a standalone content Artifact against your Environment’s Policies. Use this endpoint to evaluate profile pictures, user uploads, AI-generated images, and more.

How It Works

You submit a content Artifact (e.g., an image via URL or base64)
Conditions select the applicable Policies and Metrics for this Artifact
White Circle evaluates Policies synchronously and queues Metrics asynchronously
You receive synchronous Policy results, and selected Metrics continue asynchronously.

Image Artifacts are checked synchronously — you receive results immediately in the response.

mime_type is optional for all submission methods. White Circle detects the image format automatically from the content bytes.

Request Overview

Field	Type	Required	Description
`content`	object	✓	Artifact content payload. See Content Constraints below.
`content.kind`	string	✓	Content type: `"image"`
`content.url`	string		URL to fetch the image from. Provide either `url` or `data`, not both.
`content.data`	string		Base64-encoded image data. Provide either `url` or `data`, not both.
`content.mime_type`	string		MIME type (e.g., `image/jpeg`). Auto-detected if omitted.
`environment_id`	string		Optional Environment override. If omitted, White Circle uses the Environment associated with your API key.
`deployment_id`	string		Deprecated — predecessor of `environment_id`, still accepted for backwards compatibility. Prefer `environment_id`.
`role`	string		The role that produced this Artifact. Controls which Policies apply. See Role-Based Filtering below.
`external_artifact_id`	string		Your custom Artifact tracking ID. See External Artifact ID below.
`internal_session_id`	string		Attach Artifact to an existing Session by its system-generated UUID.
`external_session_id`	string		Attach Artifact to an existing Session by your custom session ID.
`metadata`	object		Arbitrary key-value metadata.

Response Overview

Field	Type	Description
`flagged`	boolean \| null	`true` if any Policy was violated. `null` while processing or on failure.
`status`	string	Check status: `"completed"`, `"processing"`, or `"failed"`. Images are always `"completed"`.
`policies`	object	Map of Policy IDs to their violation statuses
`kind`	string	Echo of `content.kind` from request (e.g., `"image"`)
`internal_artifact_id`	string	System-generated UUID for this Artifact
`external_artifact_id`	string	Your custom Artifact tracking ID (if provided)
`external_session_id`	string	External ID of the linked Session (if attached)
`internal_session_id`	string	System-generated UUID of the linked Session (if attached)
`updated_at`	string	ISO 8601 last update timestamp
`created_at`	string	ISO 8601 creation timestamp
`note`	string	Informational message when applicable (e.g., why an image fetch failed)

Each Policy in the policies object includes:

flagged — Whether this specific Policy was violated
name — Human-readable Policy name
enabled_by_conditions — The Conditions that selected this Policy, which is why it was evaluated. Absent when no Condition was involved.

Artifact Statuses

Status	Description
`completed`	Check finished. `flagged` contains the result.
`processing`	Async check in progress, reserved for future content types (website, video, audio). `flagged` is `null`.
`failed`	Check could not complete (e.g., image fetch timed out). `flagged` is `null`. See `note` field.

Checking image Artifacts is always synchronous — the response always has status "completed".

External Artifact ID

Use external_artifact_id to track Artifacts with your own identifiers. This is useful for:

Deduplicating checks for the same content
Looking up results later via Get Artifact Results
Tracking standalone artifact checks with your own ID

{
  "environment_id": "your-environment-id",
  "content": {
    "kind": "image",
    "url": "https://cdn.example.com/uploads/avatar-42.jpg"
  },
  "external_artifact_id": "user-avatar-42"
}

If multiple artifacts share the same external_artifact_id, White Circle returns the latest artifact version within the same Environment on lookup.

Use Images with Events

Use the standalone artifact endpoint when you want to check and retrieve an image as its own object. Use Artifact Events when you want to check an image as part of an Events workflow with run_id, event_id, and internal_event_id.

{
  "run_id": "run_image_review_123",
  "event": {
    "type": "artifact",
    "content": {
      "kind": "image",
      "url": "https://storage.example.com/uploads/photo.jpg"
    },
    "event_id": "evt_inline_image_1"
  }
}

For new Events integrations, prefer Artifact Events when the image belongs to the same interaction as messages, tool calls, agent state, or reasoning.

Role-Based Filtering

The role field controls which Policies are evaluated against the artifact based on each Policy’s Applies To setting (input, output, or any).

`role` value	Policies applied
`"user"`, `"system"`, `"developer"`, `"tool"`	`input` + `any` policies
`"assistant"`	`output` + `any` policies
omitted / `null`	`any` policies only

Use this to apply the right set of Policies depending on who produced the content. For example, pass "user" for user-uploaded images and "assistant" for AI-generated images.

{
  "role": "assistant",
  "content": {
    "kind": "image",
    "url": "https://cdn.example.com/ai-generated-image.png"
  },
  "environment_id": "your-environment-id"
}

Role strings with postfixes (e.g., "user-12345", "assistant-v2") are normalized to their base role. Invalid role values are treated the same as omitting the field.

Content Constraints

Constraint	Value
Supported formats	JPEG, PNG, WebP, GIF, SVG, BMP, ICO, HEIC
Max file size	20 MB
Max dimension	8,192 px (width or height)
Max total pixels	50,000,000
URL fetch timeout	5,000 ms
Max URL redirects	5

When you submit an image by URL, ensure the server’s Content-Type response header matches the image’s actual format.

Authorizations

Authorization

string

header

required

API Key required. Format: Bearer wc-your-api-key

Headers

whitecircle-version

string

required

API Version

Body

application/json

content

object

required

Hide child attributes

content.kind

string

required

content.data

string | null

content.mime_type

string | null

content.name

string | null

content.url

string | null

deployment_id

string | null

external_artifact_id

string | null

external_session_id

string | null

internal_session_id

string | null

metadata

null | object

Hide child attributes

metadata.{key}

object

Hide child attributes

metadata.{key}.{key}

role

string | null

span_id

string | null

trace_id

string | null

Response

Success

policies

object

required

Hide child attributes

policies.{key}

object

Hide child attributes

policies.{key}.flagged

boolean

required

policies.{key}.flagged_source

string[]

required

policies.{key}.name

string

required

kind

string

required

status

string

required

internal_artifact_id

string

required

flagged

boolean | null

updated_at

string | null

external_artifact_id

string | null

external_session_id

string | null

internal_session_id

string | null

created_at

string | null

note

string | null

⌘I

cURL

curl --request POST \
  --url https://eu.whitecircle.com/api/artifact \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'whitecircle-version: <whitecircle-version>' \
  --data '
{
  "content": {
    "kind": "<string>",
    "data": "<string>",
    "mime_type": "<string>",
    "name": "<string>",
    "url": "<string>"
  },
  "deployment_id": "<string>",
  "external_artifact_id": "<string>",
  "external_session_id": "<string>",
  "internal_session_id": "<string>",
  "metadata": {},
  "role": "<string>",
  "span_id": "<string>",
  "trace_id": "<string>"
}
'

import requests

url = "https://eu.whitecircle.com/api/artifact"

payload = {
    "content": {
        "kind": "<string>",
        "data": "<string>",
        "mime_type": "<string>",
        "name": "<string>",
        "url": "<string>"
    },
    "deployment_id": "<string>",
    "external_artifact_id": "<string>",
    "external_session_id": "<string>",
    "internal_session_id": "<string>",
    "metadata": {},
    "role": "<string>",
    "span_id": "<string>",
    "trace_id": "<string>"
}
headers = {
    "whitecircle-version": "<whitecircle-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'whitecircle-version': '<whitecircle-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    content: {
      kind: '<string>',
      data: '<string>',
      mime_type: '<string>',
      name: '<string>',
      url: '<string>'
    },
    deployment_id: '<string>',
    external_artifact_id: '<string>',
    external_session_id: '<string>',
    internal_session_id: '<string>',
    metadata: {},
    role: '<string>',
    span_id: '<string>',
    trace_id: '<string>'
  })
};

fetch('https://eu.whitecircle.com/api/artifact', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://eu.whitecircle.com/api/artifact",
  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([
    'content' => [
        'kind' => '<string>',
        'data' => '<string>',
        'mime_type' => '<string>',
        'name' => '<string>',
        'url' => '<string>'
    ],
    'deployment_id' => '<string>',
    'external_artifact_id' => '<string>',
    'external_session_id' => '<string>',
    'internal_session_id' => '<string>',
    'metadata' => [
        
    ],
    'role' => '<string>',
    'span_id' => '<string>',
    'trace_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "whitecircle-version: <whitecircle-version>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://eu.whitecircle.com/api/artifact"

	payload := strings.NewReader("{\n  \"content\": {\n    \"kind\": \"<string>\",\n    \"data\": \"<string>\",\n    \"mime_type\": \"<string>\",\n    \"name\": \"<string>\",\n    \"url\": \"<string>\"\n  },\n  \"deployment_id\": \"<string>\",\n  \"external_artifact_id\": \"<string>\",\n  \"external_session_id\": \"<string>\",\n  \"internal_session_id\": \"<string>\",\n  \"metadata\": {},\n  \"role\": \"<string>\",\n  \"span_id\": \"<string>\",\n  \"trace_id\": \"<string>\"\n}")

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

	req.Header.Add("whitecircle-version", "<whitecircle-version>")
	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(string(body))

}

HttpResponse<String> response = Unirest.post("https://eu.whitecircle.com/api/artifact")
  .header("whitecircle-version", "<whitecircle-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"content\": {\n    \"kind\": \"<string>\",\n    \"data\": \"<string>\",\n    \"mime_type\": \"<string>\",\n    \"name\": \"<string>\",\n    \"url\": \"<string>\"\n  },\n  \"deployment_id\": \"<string>\",\n  \"external_artifact_id\": \"<string>\",\n  \"external_session_id\": \"<string>\",\n  \"internal_session_id\": \"<string>\",\n  \"metadata\": {},\n  \"role\": \"<string>\",\n  \"span_id\": \"<string>\",\n  \"trace_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://eu.whitecircle.com/api/artifact")

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

request = Net::HTTP::Post.new(url)
request["whitecircle-version"] = '<whitecircle-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"content\": {\n    \"kind\": \"<string>\",\n    \"data\": \"<string>\",\n    \"mime_type\": \"<string>\",\n    \"name\": \"<string>\",\n    \"url\": \"<string>\"\n  },\n  \"deployment_id\": \"<string>\",\n  \"external_artifact_id\": \"<string>\",\n  \"external_session_id\": \"<string>\",\n  \"internal_session_id\": \"<string>\",\n  \"metadata\": {},\n  \"role\": \"<string>\",\n  \"span_id\": \"<string>\",\n  \"trace_id\": \"<string>\"\n}"

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

{
  "policies": {},
  "kind": "<string>",
  "status": "<string>",
  "internal_artifact_id": "<string>",
  "flagged": true,
  "updated_at": "<string>",
  "external_artifact_id": "<string>",
  "external_session_id": "<string>",
  "internal_session_id": "<string>",
  "created_at": "<string>",
  "note": "<string>"
}

First Steps

Use Cases

Integrations

Events

Conditions

Artifacts

Policy

Metric

User

How It Works

Request Overview

Response Overview

Artifact Statuses

External Artifact ID

Use Images with Events

Role-Based Filtering

Content Constraints

Authorizations

Headers

Body

Response

​How It Works

​Request Overview

​Response Overview

​Artifact Statuses

​External Artifact ID

​Use Images with Events

​Role-Based Filtering

​Content Constraints

Authorizations

Headers

Body

Response

How It Works

Request Overview

Response Overview

Artifact Statuses

External Artifact ID

Use Images with Events

Role-Based Filtering

Content Constraints