> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getlimina.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Usage Quickstart
> API Quickstart
日本語
This guide walks through the main features of the Limina API. It focuses on pure text applications, but can extend to [processing files](/configuration-and-operations/working-with-files/processing-files/index).
This guide uses Limina's cloud API. Get a [free API key](https://portal.getlimina.ai/?from=GettingStarted) to run the examples.
If you're using the container instead, follow the [container quickstart](/container-quickstart/quickstart-guide) and replace the endpoint with `http://localhost:8080`.
## Basic Use
The `process/text` endpoint accepts a list of text strings and replaces each piece of PII found with a redaction marker. A simple request looks like this:
```json Request Body wrap lines theme={"theme":"poimandres"}
{
"text": [
"Thank you for calling the Georgia Division of Transportation. My name is miss Johanna, and it is a pleasure assisting you today. For security reasons, may I please have your Social Security number? Yes, 614-5555 01."
]
}
```
```shell cURL wrap lines theme={"theme":"poimandres"}
curl --location 'https://api.private-ai.com/community/v4/process/text' \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '{
"text": [
"Thank you for calling the Georgia Division of Transportation. My name is miss Johanna, and it is a pleasure assisting you today. For security reasons, may I please have your Social Security number? Yes, 614-5555 01."
]
}'
```
```python Python wrap lines theme={"theme":"poimandres"}
import requests
r = requests.post(
url="https://api.private-ai.com/community/v4/process/text",
headers={"x-api-key": ""},
json={
"text": [
"Thank you for calling the Georgia Division of Transportation. My name is miss Johanna, and it is a pleasure assisting you today. For security reasons, may I please have your Social Security number? Yes, 614-5555 01."
]
},
)
results = r.json()
print(results)
```
```python Python Client wrap lines theme={"theme":"poimandres"}
from privateai_client import PAIClient
from privateai_client import request_objects
client = PAIClient(url="https://api.private-ai.com/community/v4/", api_key="")
text_request = request_objects.process_text_obj(text=["Thank you for calling the Georgia Division of Transportation. My name is miss Johanna, and it is a pleasure assisting you today. For security reasons, may I please have your Social Security number? Yes, 614-5555 01."])
response = client.process_text(text_request)
print(response.processed_text)
```
The response contains two main outputs:
* `processed_text`, the redacted, masked or synthetic text as defined by `processed_text` in the input
* `entities`, a list of each PII found, which is useful for PII detection and NER (Named Entity Recognition)
```json Response wrap lines expandable theme={"theme":"poimandres"}
[
{
"processed_text": "Thank you for calling the [ORGANIZATION_1]. My name is miss [NAME_GIVEN_1], and it is a pleasure assisting you today. For security reasons, may I please have your Social Security number? Yes, [SSN_1].",
"entities": [
{
"processed_text": "ORGANIZATION_1",
"text": "Georgia Division of Transportation",
"location": {
"stt_idx": 26,
"end_idx": 60,
"stt_idx_processed": 26,
"end_idx_processed": 42
},
"best_label": "ORGANIZATION",
"labels": {
"LOCATION_STATE": 0.2403,
"LOCATION": 0.2342,
"ORGANIZATION": 0.8967
}
},
{
"processed_text": "NAME_GIVEN_1",
"text": "Johanna",
"location": {
"stt_idx": 78,
"end_idx": 85,
"stt_idx_processed": 60,
"end_idx_processed": 74
},
"best_label": "NAME_GIVEN",
"labels": {
"NAME_GIVEN": 0.9127,
"NAME": 0.9018
}
},
{
"processed_text": "SSN_1",
"text": "614-5555 01",
"location": {
"stt_idx": 203,
"end_idx": 214,
"stt_idx_processed": 192,
"end_idx_processed": 199
},
"best_label": "SSN",
"labels": {
"SSN": 0.913
}
}
],
"entities_present": true,
"characters_processed": 215,
"languages_detected": {
"en": 0.920992910861969
}
}
]
```
## Processing Related Examples
If the elements in the list of strings are related, the `link_batch` parameter can be used to share context throughout the list.
```json Request Body wrap lines highlight={6} theme={"theme":"poimandres"}
{
"text": [
"My phone number is",
"2345435"
],
"link_batch": true
}
```
```shell cURL wrap lines theme={"theme":"poimandres"}
curl --location 'https://api.private-ai.com/community/v4/process/text' \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '{
"text": [
"My phone number is",
"2345435"
],
"link_batch": true
}'
```
```python Python wrap lines theme={"theme":"poimandres"}
import requests
r = requests.post(
url="https://api.private-ai.com/community/v4/process/text",
headers={"x-api-key": ""},
json={
"text": [
"My phone number is",
"2345435",
],
"link_batch": True,
},
)
results = r.json()
print(results)
```
```python Python Client wrap lines theme={"theme":"poimandres"}
from privateai_client import PAIClient
from privateai_client import request_objects
client = PAIClient(url="https://api.private-ai.com/community/v4/", api_key="")
text_request = request_objects.process_text_obj(text=["My phone number is", "2345435"], link_batch=True)
response = client.process_text(text_request)
print(response.processed_text)
```
This ensures that the inputs are joined before going to the PII detection system. This way the model sees `My phone number is 2345435` instead of `My phone number is` and `2345435` as two unrelated messages. This allows the phone number to be identified correctly.
```shell Redacted Text wrap theme={"theme":"poimandres"}
["My phone number is", "[PHONE_NUMBER_1]"]
```
```json Full Response wrap theme={"theme":"poimandres"}
[
{
"processed_text": "My phone number is",
"entities": [],
"entities_present": false,
"characters_processed": 18,
"languages_detected": {
"en": 0.8986189365386963
}
},
{
"processed_text": "[PHONE_NUMBER_1]",
"entities": [
{
"processed_text": "PHONE_NUMBER_1",
"text": "2345435",
"location": {
"stt_idx": 0,
"end_idx": 7,
"stt_idx_processed": 0,
"end_idx_processed": 16
},
"best_label": "PHONE_NUMBER",
"labels": {
"PHONE_NUMBER": 0.9166
}
}
],
"entities_present": true,
"characters_processed": 7,
"languages_detected": {}
}
]
```
## Customizing Entity Detection With Selective Redaction
The above example identifies and removes all non-beta entity types. Granular control over entity detection and redaction can be set using [Entity Selectors](/configuration-and-operations/entity-detection-and-redaction/customizing-detection). For example, to only redact the SSN:
```json Request Body wrap lines highlight={5-14} theme={"theme":"poimandres"}
{
"text": [
"Thank you for calling the Georgia Division of Transportation. My name is miss Johanna, and it is a pleasure assisting you today. For security reasons, may I please have your Social Security number? Yes, 614-5555 01."
],
"entity_detection": {
"entity_types": [
{
"type": "ENABLE",
"value": [
"SSN"
]
}
]
}
}
```
```shell cURL wrap lines theme={"theme":"poimandres"}
curl --location 'https://api.private-ai.com/community/v4/process/text' \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '{
"text": [
"Thank you for calling the Georgia Division of Transportation. My name is miss Johanna, and it is a pleasure assisting you today. For security reasons, may I please have your Social Security number? Yes, 614-5555 01."
],
"entity_detection": {
"entity_types": [
{
"type": "ENABLE",
"value": [
"SSN"
]
}
]
}
}'
```
```python Python wrap lines theme={"theme":"poimandres"}
import requests
r = requests.post(
url="https://api.private-ai.com/community/v4/process/text",
headers={"x-api-key": ""},
json={
"text": [
"Thank you for calling the Georgia Division of Transportation. My name is miss Johanna, and it is a pleasure assisting you today. For security reasons, may I please have your Social Security number? Yes, 614-5555 01."
],
"entity_detection": {"entity_types": [{"type": "ENABLE", "value": ["SSN"]}]},
},
)
results = r.json()
print(results)
```
```python Python Client wrap lines theme={"theme":"poimandres"}
from privateai_client import PAIClient
from privateai_client import request_objects
client = PAIClient(url="https://api.private-ai.com/community/v4/", api_key="")
entity_detection_object = request_objects.entity_detection_obj(entity_types=[request_objects.entity_type_selector_obj(type="ENABLE", value=["SSN"])])
text_request = request_objects.process_text_obj(text=["Thank you for calling the Georgia Division of Transportation. My name is miss Johanna, and it is a pleasure assisting you today. For security reasons, may I please have your Social Security number? Yes, 614-5555 01."], entity_detection=entity_detection_object)
response = client.process_text(text_request)
print(response.processed_text)
```
The result of this selective redaction is below:
```text Redacted Text wrap theme={"theme":"poimandres"}
Thank you for calling the Georgia Division of Transportation. My name is miss Johanna, and it is a pleasure assisting you today. For security reasons, may I please have your Social Security number? Yes, [SSN_1].
```
```json Full Response wrap theme={"theme":"poimandres"}
[
{
"processed_text": "Thank you for calling the Georgia Division of Transportation. My name is miss Johanna, and it is a pleasure assisting you today. For security reasons, may I please have your Social Security number? Yes, [SSN_1].",
"entities": [
{
"processed_text": "SSN_1",
"text": "614-5555 01",
"location": {
"stt_idx": 203,
"end_idx": 214,
"stt_idx_processed": 203,
"end_idx_processed": 210
},
"best_label": "SSN",
"labels": {
"SSN": 0.913
}
}
],
"entities_present": true,
"characters_processed": 215,
"languages_detected": {
"en": 0.920992910861969
}
}
]
```
## Adding Allow & Block Lists
You can also customize PII detection and redaction using enable/disable [Entity Selectors](/configuration-and-operations/entity-detection-and-redaction/customizing-detection#enabling-and-disabling-entity-types) or regex-based [Filters](/configuration-and-operations/entity-detection-and-redaction/customizing-detection#filters), enabling custom handling for company-specific identifiers such as employee IDs or internal database IDs.
The example below shows how to combine [Entity Selectors](/configuration-and-operations/entity-detection-and-redaction/customizing-detection) with [Filters](/configuration-and-operations/entity-detection-and-redaction/customizing-detection#filters) for fine-grained control. In this HR claim scenario, an employee reports a medical injury and requests accommodation. Here, we demonstrate:
* Two regex-based [block filters](/configuration-and-operations/entity-detection-and-redaction/customizing-detection#block-filter) defining custom entity types for employee IDs and business units, overriding Limina's defaults.
* Disabling the injury entity, which may be required for insurance-related workflows.
* Using a list for the `text` payload, as expected in conversational contexts, and enabling `link_batch` to maintain redaction context across the full thread.
* Disabling numbering of redaction markers.
```json Request Body wrap lines highlight={22-33} theme={"theme":"poimandres"}
{
"text": [
"Hello Xavier, can you tell me your employee ID?",
"Yep, my Best Corp ID is GID-45434, and my SIN is 690 871 283",
"Okay, thanks Xavier, why are you calling today?",
"I broke my right leg on the 31st and I'm waiting for my x-ray results. dr. zhang, mercer health centre.",
"Oh, so sorry to hear that! How can we help?",
"I won't be able to come back to the office in NYC for a while",
"No problem Xavier, I will enter a short term work from home for you. You're all set!",
"Thanks so much Carole!"
],
"link_batch": true,
"entity_detection": {
"entity_types": [
{
"type": "DISABLE",
"value": [
"INJURY"
]
}
],
"filter": [
{
"type": "BLOCK",
"entity_type": "EMPLOYEE_ID",
"pattern": "GID-\\d{5}"
},
{
"type": "BLOCK",
"entity_type": "BUSINESS_UNIT",
"pattern": "Best Corp"
}
],
"return_entity": true
},
"processed_text": {
"type": "MARKER",
"pattern": "[BEST_ENTITY_TYPE]"
}
}
```
```shell cURL wrap lines theme={"theme":"poimandres"}
curl --location 'https://api.private-ai.com/community/v4/process/text' \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '
{
"text": [
"Hello Xavier, can you tell me your employee ID?",
"Yep, my Best Corp ID is GID-45434, and my SIN is 690 871 283",
"Okay, thanks Xavier, why are you calling today?",
"I broke my right leg on the 31st and I''m waiting for my x-ray results. dr. zhang, mercer health centre.",
"Oh, so sorry to hear that! How can we help?",
"I won''t be able to come back to the office in NYC for a while",
"No problem Xavier, I will enter a short term work from home for you. You''re all set!",
"Thanks so much Carole!"
],
"link_batch": true,
"entity_detection": {
"entity_types": [
{
"type": "DISABLE",
"value": [
"INJURY"
]
}
],
"filter": [
{
"type": "BLOCK",
"entity_type": "EMPLOYEE_ID",
"pattern": "GID-\\d{5}"
},
{
"type": "BLOCK",
"entity_type": "BUSINESS_UNIT",
"pattern": "Best Corp"
}
],
"return_entity": true
},
"processed_text": {
"type": "MARKER",
"pattern": "[BEST_ENTITY_TYPE]"
}
}'
```
```python Python wrap lines theme={"theme":"poimandres"}
import requests
r = requests.post(
url="https://api.private-ai.com/community/v4/process/text",
headers={"x-api-key": ""},
json={
"text": [
"Hello Xavier, can you tell me your employee ID?",
"Yep, my Best Corp ID is GID-45434, and my SIN is 690 871 283",
"Okay, thanks Xavier, why are you calling today?",
"I broke my right leg on the 31st and I'm waiting for my x-ray results. dr. zhang, mercer health centre.",
"Oh, so sorry to hear that! How can we help?",
"I won't be able to come back to the office in NYC for a while",
"No problem Xavier, I will enter a short term work from home for you. You're all set!",
"Thanks so much Carole!",
],
"link_batch": True,
"entity_detection": {
"entity_types": [{"type": "DISABLE", "value": ["INJURY"]}],
"filter": [
{
"type": "BLOCK",
"entity_type": "EMPLOYEE_ID",
"pattern": "GID-\\d{5}",
},
{
"type": "BLOCK",
"entity_type": "BUSINESS_UNIT",
"pattern": "Best Corp",
},
],
"return_entity": True,
},
"processed_text": {"type": "MARKER", "pattern": "[BEST_ENTITY_TYPE]"},
},
)
results = r.json()
print(results)
```
```python Python Client wrap lines theme={"theme":"poimandres"}
from privateai_client import PAIClient
from privateai_client import request_objects
client = PAIClient(url="https://api.private-ai.com/community/v4/", api_key="")
filter_employee = request_objects.filter_selector_obj(type="BLOCK", entity_type="EMPLOYEE_ID", pattern="GID-\\d{5}")
filter_bu = request_objects.filter_selector_obj(type="BLOCK", entity_type="BUSINESS_UNIT", pattern="Best Corp")
entity_detection_object = request_objects.entity_detection_obj(entity_types=[request_objects.entity_type_selector_obj(type="DISABLE", value=["INJURY"])],
filter=[filter_employee, filter_bu],
return_entity=True)
processed_text_object = request_objects.processed_text_obj(type="MARKER", pattern="[BEST_ENTITY_TYPE]")
text_request = request_objects.process_text_obj(text=[
"Hello Xavier, can you tell me your employee ID?",
"Yep, my Best Corp ID is GID-45434, and my SIN is 690 871 283",
"Okay, thanks Xavier, why are you calling today?",
"I broke my right leg on the 31st and I'm waiting for my x-ray results. dr. zhang, mercer health centre.",
"Oh, so sorry to hear that! How can we help?",
"I won't be able to come back to the office in NYC for a while",
"No problem Xavier, I will enter a short term work from home for you. You're all set!",
"Thanks so much Carole!"
],
link_batch=True,
entity_detection=entity_detection_object,
processed_text=processed_text_object,
)
response = client.process_text(text_request)
print(response.processed_text)
```
The above request yields this response:
```python Redacted Text wrap theme={"theme":"poimandres"}
['Hello [NAME_GIVEN], can you tell me your employee ID?', 'Yep, my [BUSINESS_UNIT] ID is [EMPLOYEE_ID], and my SIN is [SSN]', 'Okay, thanks [NAME_GIVEN], why are you calling today?', "I broke my right leg on the [DATE] and I'm waiting for my [MEDICAL_PROCESS] results. [NAME_MEDICAL_PROFESSIONAL], [ORGANIZATION_MEDICAL_FACILITY].", 'Oh, so sorry to hear that! How can we help?', "I won't be able to come back to the office in [LOCATION_CITY] for a while", "No problem [NAME_GIVEN], I will enter a short term work from home for you. You're all set!", 'Thanks so much [NAME_GIVEN]!']
```
## Generating Synthetic Entities (Beta)
In addition to replacing PII with redaction markers, tokens, or masks, Limina can generate synthetic PII; realistic fake replacements created with an ML model that fit the surrounding context. This offers several advantages:
* Synthetic PII preserves most of the original text, reducing the risk of introducing bias compared to generators that create entirely new data, and improving utility for downstream tasks like sentiment analysis.
* Even though our [PII detection engine leads the market](https://www.getlimina.ai/en/resources/whitepaper), it isn't perfect. Synthetic PII ensures that any PII detection misses are hidden amongst realistic, fake PII, strengthening protection against re-identification.
* Synthetic entities resemble natural language more closely than redaction markers or hashes, minimizing disruption to downstream ML systems.
To enable synthetic PII generation, set the `processed_text` object's marker type to `SYNTHETIC` in your API request.
```json Request Body wrap lines highlight={6} theme={"theme":"poimandres"}
{
"text": [
"Hello, my name is May. I am the aunt of Jessica Parker. We live in Toronto, Canada."
],
"processed_text": {
"type": "SYNTHETIC"
}
}
```
```shell cURL wrap lines theme={"theme":"poimandres"}
curl --location 'https://api.private-ai.com/community/v4/process/text' \
--header 'Content-Type: application/json' \
--header 'x-api-key: ' \
--data '{
"text": [
"Hello, my name is May. I am the aunt of Jessica Parker. We live in Toronto, Canada."
],
"processed_text": {
"type": "SYNTHETIC"
}
}'
```
```python Python wrap lines theme={"theme":"poimandres"}
import requests
r = requests.post(
url="https://api.private-ai.com/community/v4/process/text",
headers={"x-api-key": ""},
json={
"text": [
"Hello, my name is May. I am the aunt of Jessica Parker. We live in Toronto, Canada."
],
"processed_text": {"type": "SYNTHETIC"},
},
)
results = r.json()
print(results)
```
```python Python Client wrap lines theme={"theme":"poimandres"}
from privateai_client import PAIClient
from privateai_client import request_objects
client = PAIClient(url="https://api.private-ai.com/community/v4/", api_key="")
text_request = request_objects.process_text_obj(text=["Hello, my name is May. I am the aunt of Jessica Parker. We live in Toronto, Canada."],
processed_text=request_objects.processed_text_obj(type="SYNTHETIC"))
response = client.process_text(text_request)
print(response.processed_text)
```
Yields the following response:
```text Redacted Text wrap theme={"theme":"poimandres"}
Hello, my name is Ben. I am the aunt of Michael Morley. We live in Ekshaku, Sweden.
```
```json Full Response wrap theme={"theme":"poimandres"}
[
{
"processed_text": "Hello, my name is Ben. I am the aunt of Michael Morley. We live in Ekshaku, Sweden.",
"entities": [
{
"processed_text": "Ben",
"text": "May",
"location": {
"stt_idx": 18,
"end_idx": 21,
"stt_idx_processed": 18,
"end_idx_processed": 21
},
"best_label": "NAME_GIVEN",
"labels": {
"NAME_GIVEN": 0.9234,
"NAME": 0.8903
}
},
{
"processed_text": "Michael Morley",
"text": "Jessica Parker",
"location": {
"stt_idx": 40,
"end_idx": 54,
"stt_idx_processed": 40,
"end_idx_processed": 54
},
"best_label": "NAME",
"labels": {
"NAME_GIVEN": 0.4595,
"NAME": 0.9178,
"NAME_FAMILY": 0.4567
}
},
{
"processed_text": "Ekshaku, Sweden",
"text": "Toronto, Canada",
"location": {
"stt_idx": 67,
"end_idx": 82,
"stt_idx_processed": 67,
"end_idx_processed": 82
},
"best_label": "LOCATION",
"labels": {
"LOCATION_CITY": 0.3177,
"LOCATION": 0.9268,
"LOCATION_COUNTRY": 0.3185
}
}
],
"entities_present": true,
"characters_processed": 83,
"languages_detected": {
"en": 0.8507365584373474
}
}
]
```