Detect Text Encoding

file.detect_text_encoding

ProductionEngine wrapper (Class A)Deterministicstrictfastv1.0.0

File inputNo network

Overview

You send a binary file_ref up to 5 MiB. We inspect a 1 KiB–1 MiB sample (256 KiB unless you set sampleBytes), report a BOM when present, and return ranked ICU candidates from a closed allowlist. Confidence is advisory: ASCII-only input never claims certainty. This does not decode the file or expose arbitrary JVM charsets.

Guessing a charset from a filename or a platform default silently mojibakes later decode steps.

Reliability

ICU confidence is advisory. ASCII-only input is flagged and capped. ITEM_LIMIT_EXCEEDED — trigger: the file exceeds 5 MiB; retryable: no; next: sample a smaller artifact.

Context footprint

BOM, candidates, binaryLikely, sampledBytes, asciiOnly. A successful call costs 1 execution credit.

When to use it

When a managed file's encoding is unknown and you need an advisory candidate list plus BOM.

When you already know the encoding, or you need the decoded text in this call.

Scope

Note

Estimates text encoding of a bounded file sample using a per-call ICU CharsetDetector.

Non-goals

Does not decode or convert the file
Does not guarantee language identification
Does not expose arbitrary JVM charset names

Properties

IdempotentRetry safeStreaming supportedFile input supportedRequires external service

Capabilities

analysisencodingparsing

Cost & billing

Flat rate per invocation

MetercallsBillable onsuccessCost per call1 credit

File handling

Accepts file_refProduces file_refMax input2 MBMax file size5 MB

File limits

Constraints this skill applies to your input and generated files. The “Limited by” column shows the static source of each cap; none of these can be raised by upgrading your plan.

Limit	Value	Limited by
Maximum size per input file	5 MiB	Skill and platform maximum
Maximum total input size	5 MiB	Skill maximum
Maximum number of input files	1	Skill maximum

How we handle your data

Protected temp storage

What this means

This skill may temporarily store files or intermediate data only to complete execution. Temporary data is protected and automatically deleted.

Squillify guarantees

Runs inside Squillify
This skill runs inside Squillify.
Payloads are not sent to an external service by this skill.
Temporary execution only storage
Squillify does not permanently store submitted payloads.
Telemetry records metadata only, not submitted content.
Submitted payloads are not used for training.
Submitted payloads are not reviewed by humans.
This skill does not target sensitive data.
The response may contain submitted or transformed content.

Your responsibility

Squillify does not determine whether submitted content is sensitive. Your application is responsible for deciding what data it is allowed to submit. Your application is responsible for securing the response.

Read the Microskill Data Handling Policy

Input schema

Field	Type	Required	Description
file_ref	string	Yes	Tenant-scoped binary file up to 5 MiB whose encoding is estimated from a bounded sample.
sampleBytes	integer	No	Prefix length in bytes, 1024 through 1048576. Omit it for 262144.
allowlist	array	No	Optional filter of 1 through 14 published encoding names; omit it to keep the full allowlist.

Output schema

Field	Type	Required	Description
bom	string	No	Canonical BOM encoding when a BOM is present; omit this field when the sample has no BOM.
candidates	array	Yes	From 0 through 14 ranked candidates; empty when the sample is binary-likely without a BOM.
binaryLikely	boolean	Yes	True when the inspected prefix is NUL-heavy or control-heavy enough to look binary.
sampledBytes	integer	Yes	How many prefix bytes were handed to ICU, at most sampleBytes and the file size.
asciiOnly	boolean	Yes	True when every sampled byte is 7-bit and no BOM is present; confidence is then capped.

API contract

POST /v1/execute

curl

curl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"file.detect_text_encoding","input":{"file_ref":"squillify://files/f-utf8-bom"}}'

Integrations

TypeScript SDK

import { Squillify } from "@squillify/sdk";

const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });

const { output } = await sq.execute("file.detect_text_encoding", {"file_ref":"squillify://files/f-utf8-bom"});

Errors

Code	HTTP	Retryable	Description
VALIDATION_ERROR	400	No	The request payload failed schema validation.
UNAUTHORIZED	401	No	Missing or invalid API key.
SKILL_NOT_ACCESSIBLE	403	No	The API key is not granted access to this skill.
SKILL_NOT_AVAILABLE_FOR_PLAN	403	No	This skill is not included in your current plan.
PLAN_ELIGIBILITY_UNAVAILABLE	503	Yes	Plan eligibility could not be decided. Retry after backoff.
SKILL_NOT_FOUND	404	No	The requested skill or version does not exist.
TENANT_RATE_LIMITED	429	Yes	Request rate limit exceeded. Retry after backoff.
QUOTA_EXCEEDED	429	Yes	Plan quota exhausted. Retryable once the quota period resets.
EXECUTION_TIMEOUT	504	Yes	Execution exceeded the allowed time budget.
ITEM_LIMIT_EXCEEDED	429	No	A size, quota, rate, or time limit was exceeded.

Other limits

Limit	Value
Recommended inline bytes	32 KiB

Limitations

Does not decode or convert the file
Does not guarantee language identification
Does not expose arbitrary JVM charset names
Treating the top candidate as certain on ASCII
Decoding the payload in the same call

How to call

POST /v1/execute (requires authentication)

Request bodyjson

{
  "skillKey": "file.detect_text_encoding",
  "input": {
    "file_ref": "squillify://files/f-utf8-bom"
  }
}

Examples

UTF-8 BOM is reported

Inputjson

{
  "file_ref": "squillify://files/f-utf8-bom"
}

Expected outputjson

{
  "binaryLikely": false,
  "sampledBytes": 5,
  "bom": "UTF-8",
  "asciiOnly": false,
  "candidates": []
}

Tip

EF BB BF plus hi is reported as a UTF-8 BOM

ASCII does not claim certainty