> ## 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

<Steps>
  <Step title="Set your API key">
    All requests require your API key in the `x-api-key` header.

    ```bash theme={null}
    export PANGRAM_API_KEY=<your API key>
    ```
  </Step>

  <Step title="Submit an AI detection task">
    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",
        "public_dashboard_link": false
      }'
    ```

    **Example Response**

    ```json theme={null}
    {
      "task_id": "123e4567-e89b-12d3-a456-426614174000"
    }
    ```
  </Step>

  <Step title="Poll for the completed result">
    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": "3.0",
      "headline": "AI Detected",
      "prediction": "We are confident that this document is a mix of AI-generated, AI-assisted, and human-written content",
      "prediction_short": "Mixed",
      "fraction_ai": 0.70,
      "fraction_ai_assisted": 0.20,
      "fraction_human": 0.10,
      "num_ai_segments": 7,
      "num_ai_assisted_segments": 2,
      "num_human_segments": 1,
      "windows": [
        {
          "text": "The text to analyze",
          "label": "AI-Generated",
          "ai_assistance_score": 0.85,
          "confidence": "High",
          "start_index": 0,
          "end_index": 19,
          "word_count": 4,
          "token_length": 5
        }
      ]
    }
    ```

    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"`
  </Step>

  <Step title="Request a dashboard link">
    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",
        "public_dashboard_link": true
      }'
    ```
  </Step>

  <Step title="Submit a Bulk API job">
    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"}
        ]
      }'
    ```

    **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": []
    }
    ```
  </Step>

  <Step title="Poll and fetch bulk results">
    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"
    ```
  </Step>

  <Step title="Upload a file">
    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'
    ```
  </Step>

  <Step title="Check for plagiarism">
    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
    }
    ```
  </Step>
</Steps>

## 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 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 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.               |

If you are running into errors, please reach out at [support@pangram.com](mailto:support@pangram.com).