> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pangram.com/llms.txt
> Use this file to discover all available pages before exploring further.
# REST API Quickstart
> Get started with the Pangram REST API using cURL
All requests require your API key in the `x-api-key` header.
```bash theme={null}
export PANGRAM_API_KEY=
```
Retrieve the model selectors enabled for your API key.
```bash theme={null}
curl -X GET https://text.external-api.pangram.com/models \
-H "x-api-key: $PANGRAM_API_KEY"
```
The response is entitlement- and availability-aware:
```json theme={null}
{
"models": ["default", "pangram-4"]
}
```
Pangram AI detection uses an async task API. Submit text to create a task.
```bash theme={null}
curl -X POST https://text.external-api.pangram.com/task \
-H "Content-Type: application/json" \
-H "x-api-key: $PANGRAM_API_KEY" \
-d '{
"text": "The text to analyze",
"model": "pangram-4",
"public_dashboard_link": false
}'
```
**Example Response**
```json theme={null}
{
"task_id": "123e4567-e89b-12d3-a456-426614174000"
}
```
Poll the task endpoint until `stage` is `STAGE_SUCCESS` or `STAGE_FAILED`.
```bash theme={null}
curl -X GET https://text.external-api.pangram.com/task/123e4567-e89b-12d3-a456-426614174000 \
-H "x-api-key: $PANGRAM_API_KEY"
```
**Example Success Response**
```json theme={null}
{
"stage": "STAGE_SUCCESS",
"text": "The text to analyze",
"version": "4.0",
"headline": "Human Written",
"prediction": "We believe that this entire text is human-written.",
"prediction_short": "Human",
"fraction_ai": 0.0,
"fraction_ai_assisted": 0.0,
"fraction_human": 1.0,
"num_ai_segments": 0,
"num_ai_assisted_segments": 0,
"num_human_segments": 1,
"windows": [
{
"text": "The text to analyze",
"label": "Human Written",
"ai_assistance_score": 0.02,
"confidence": "High",
"start_index": 0,
"end_index": 19,
"word_count": 4,
"token_length": 5,
"is_humanized": false,
"humanizer_score": 0.0
}
]
}
```
Key response fields:
* `stage` — terminal task stage for completed results
* `fraction_ai` / `fraction_ai_assisted` / `fraction_human` — breakdown of text by authorship
* `windows` — segment-level classifications with confidence scores
* `headline` — summary classification, such as `"AI Detected"` or `"Human Written"`
* `is_humanized` / `humanizer_score` — Pangram 4 humanizer-head output on every window
Pass `public_dashboard_link: true` when submitting the task to get a shareable link in the completed result.
```bash theme={null}
curl -X POST https://text.external-api.pangram.com/task \
-H "Content-Type: application/json" \
-H "x-api-key: $PANGRAM_API_KEY" \
-d '{
"text": "The text to analyze",
"model": "pangram-4",
"public_dashboard_link": true
}'
```
Use `POST /bulk` for asynchronous AI detection across many inputs.
```bash theme={null}
curl -X POST https://text.external-api.pangram.com/bulk \
-H "Content-Type: application/json" \
-H "x-api-key: $PANGRAM_API_KEY" \
-d '{
"items": [
{"id": "row-001", "text": "First text to analyze"},
{"id": "row-002", "text": "Second text to analyze"}
],
"model": "pangram-4"
}'
```
**Example Response**
```json theme={null}
{
"bulk_id": "blk_123",
"status": "queued",
"total_items": 2,
"accepted_items": [
{"index": 0, "id": "row-001", "task_id": "123e4567-e89b-12d3-a456-426614174000"},
{"index": 1, "id": "row-002", "task_id": "223e4567-e89b-12d3-a456-426614174000"}
],
"failed_items": []
}
```
Poll the bulk job until `status` is `succeeded`, `failed`, or `partial`.
```bash theme={null}
curl -X GET https://text.external-api.pangram.com/bulk/blk_123 \
-H "x-api-key: $PANGRAM_API_KEY"
```
Then page through results.
```bash theme={null}
curl -X GET "https://text.external-api.pangram.com/bulk/blk_123/results?offset=0&limit=100" \
-H "x-api-key: $PANGRAM_API_KEY"
```
Send documents as multipart form data to create file-based AI detection results.
```bash theme={null}
curl -s -X POST https://file-external.api.pangram.com \
-H "x-api-key: $PANGRAM_API_KEY" \
-F "files=@modeling/deployments/test/test_document.docx" \
-F "public_dashboard_link=true" \
| jq -r '.[0].public_dashboard_link'
```
Check text against a database of online content. Note the different base URL.
```bash theme={null}
curl -X POST https://plagiarism.api.pangram.com \
-H "Content-Type: application/json" \
-H "x-api-key: $PANGRAM_API_KEY" \
-d '{
"text": "Text to check for plagiarism"
}'
```
**Example Response**
```json theme={null}
{
"text": "Text to check for plagiarism",
"plagiarism_detected": true,
"plagiarized_content": [
{
"source_url": "https://example.com/source",
"matched_text": "Text to check for plagiarism",
"similarity_score": 0.95
}
],
"total_sentences": 1,
"plagiarized_sentences": 1,
"percent_plagiarized": 100.0
}
```
The text and bulk APIs temporarily accept an omitted `model` for backward compatibility and resolve it to `"default"`. New integrations should always send a selector returned by `GET /models`. A bulk selector applies to every item in the job.
## Error Handling
| Status Code | Description |
| --------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request` | The request body is not properly formatted. |
| `401 Unauthorized` | The `x-api-key` is missing or invalid. |
| `402 Payment Required` | The account has insufficient credits. |
| `403 Forbidden` | The requested model is not enabled for the API key, or the API key does not own the requested task or bulk job. |
| `404 Not Found` | The requested task or bulk job does not exist. |
| `413 Payload Too Large` | The bulk request exceeds the maximum billable units. |
| `422 Unprocessable Entity` | The input text or model selector is invalid. |
| `429 Too Many Requests` | The API key exceeds its configured rate limit. |
| `500 Internal Server Error` | There was an error processing the request. |
| `503 Service Unavailable` | The requested model is temporarily unavailable. |
If you are running into errors, please reach out at [support@pangram.com](mailto:support@pangram.com).