API Reference

The complete REST catalogue: every endpoint, its request fields, curl examples and response shapes.

Updated Sep 2026

The PARROTSIGHT API is JSON over HTTPS. All endpoints live under https://api.parrotsight.com/v1, authenticate with a Bearer key, and accept application/json request bodies. Every response also carries a JSON body — errors included — so clients can parse failures as structured data.

Requests may be retried safely when they carry an Idempotency-Key header. Within the ten-minute idempotency window, repeating the same key returns the original result instead of executing the operation twice.

Common request headers

Header	Value	Description
Authorization	Bearer sk-ps-…	Required on all requests
Content-Type	application/json	Required on all POST bodies
Idempotency-Key	String, ≤ 64 characters	Suppresses duplicate side effects for 10 minutes
X-Parrotsight-Region	my \| sg \| id	Pins inference to a region (Enterprise)

Endpoints

Six endpoints make up the public surface. Five accept inference payloads; the sixth enumerates the models available to your key.

Method	Path	Model	Purpose
POST	/v1/chat/completions	ps-lingua-7b	Chat and instruction completion
POST	/v1/images/analyze	ps-vision-pro	Image and video-frame understanding
POST	/v1/moderations	ps-shield-base · ps-guard-max	Content safety and threat analysis
POST	/v1/documents/parse	ps-parse-pro	Structured document extraction
POST	/v1/embeddings	ps-embed-base	Text embeddings for search and RAG
GET	/v1/models	—	List models available to the key

POST /v1/chat/completions

Generates a chat completion from ps-lingua-7b. The endpoint is OpenAI-compatible, including streaming (SSE), function calling and JSON mode.

Field	Type	Required	Description
model	string	yes	Must be ps-lingua-7b
messages	array	yes	Conversation messages with role and content
temperature	number	no	Sampling temperature 0–2, default 0.7
max_tokens	integer	no	Maximum tokens to generate, default 256
stream	boolean	no	Return server-sent events, default false
response_format	object	no	Set {"type":"json_object"} for JSON mode
tools	array	no	Function schemas for tool calling

request.sh

curl https://api.parrotsight.com/v1/chat/completions \
  -H "Authorization: Bearer $PS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ps-lingua-7b",
    "messages": [
      { "role": "system", "content": "You answer in Bahasa Malaysia." },
      { "role": "user", "content": "Terangkan konsep API dalam dua ayat." }
    ],
    "max_tokens": 96,
    "stream": false
  }'

Chat completion response

response.json

{
  "id": "chatcmpl-3a71e9b2c5d84f0a6b8e1c2d3f4a5b6c",
  "object": "chat.completion",
  "created": 1756684800,
  "model": "ps-lingua-7b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "API ialah antara muka yang membenarkan dua sistem perisian bertukar data secara berstruktur. Ia membolehkan aplikasi memanggil fungsi atau mengakses data tanpa perlu memahami pelaksanaan dalaman sistem yang lain."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 55,
    "total_tokens": 79
  }
}

POST /v1/images/analyze

Analyses images and sampled video frames with ps-vision-pro, returning captions, detected objects with bounding boxes, and a scene profile. Input may be referenced by URL or supplied as base64.

Field	Type	Required	Description
model	string	no	Defaults to ps-vision-pro
image_url	string	conditional	HTTPS URL of the image (JPEG or PNG, up to 4K)
image	string	conditional	Base64-encoded image, alternative to image_url
tasks	array	no	Subset of caption, objects, scene_graph
language	string	no	Caption language: en, ms, or zh (default en)
max_frames	integer	no	Frames to sample from video, up to 128

request.sh

curl https://api.parrotsight.com/v1/images/analyze \
  -H "Authorization: Bearer $PS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ps-vision-pro",
    "image_url": "https://assets.parrotsight.com/samples/jalan-tun-razak.jpg",
    "tasks": ["caption", "objects", "scene_graph"],
    "language": "en"
  }'

Image analysis response

response.json

{
  "id": "req_vis_8c2d1f4a9b3e4c7a8d5f6e7b2a1c3d4e",
  "model": "ps-vision-pro",
  "created": 1756684800,
  "results": [
    {
      "caption": "A red motorcycle is parked at the curb beside a busy street market, with pedestrians carrying shopping bags in the background.",
      "language": "en",
      "objects": [
        { "label": "motorcycle", "confidence": 0.987, "bbox": [0.12, 0.44, 0.51, 0.82] },
        { "label": "person", "confidence": 0.941, "bbox": [0.55, 0.20, 0.83, 0.95] }
      ],
      "scene": { "outdoor": 0.99, "urban": 0.93, "daytime": 0.88 }
    }
  ],
  "usage": { "images": 1, "frames_sampled": 0 }
}

POST /v1/moderations

Runs a safety or threat pass over text. With model ps-shield-base it classifies user-generated content across fourteen safety categories with per-label confidence. With model ps-guard-max it analyses logs, alerts and telemetry for indicators of compromise and anomalous behaviour.

Field	Type	Required	Description
model	string	yes	ps-shield-base or ps-guard-max
input	string	yes	Text payload, up to 32 KB
categories	array	no	Category filters for ps-shield-base
thresholds	object	no	Per-category confidence thresholds

request.sh

curl https://api.parrotsight.com/v1/moderations \
  -H "Authorization: Bearer $PS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ps-shield-base",
    "input": "Please verify MyKad number 870101-14-5213 for account recovery."
  }'

Moderation response (ps-shield-base)

response.json

{
  "id": "modr_b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6",
  "model": "ps-shield-base",
  "created": 1756684800,
  "results": [
    {
      "flagged": true,
      "categories": {
        "violence": { "flagged": false, "score": 0.01 },
        "hate_speech": { "flagged": false, "score": 0.02 },
        "adult_content": { "flagged": false, "score": 0.01 },
        "pii_exposure": { "flagged": true, "score": 0.96 }
      },
      "category_scores": {
        "violence": 0.01,
        "hate_speech": 0.02,
        "adult_content": 0.01,
        "pii_exposure": 0.96
      }
    }
  ]
}

Threat analysis with ps-guard-max

Set model to ps-guard-max on the same endpoint to route telemetry into the threat-detection engine. Findings are ranked, mapped to MITRE ATT&CK techniques, and bundled with recommended containment actions.

request.sh

curl https://api.parrotsight.com/v1/moderations \
  -H "Authorization: Bearer $PS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ps-guard-max",
    "input": "2026-09-02T08:14Z svc-n8 authenticated from 203.0.113.41 then executed sudo -i on db-prod-01."
  }'

Threat analysis response (ps-guard-max)

response.json

{
  "id": "modr_e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "model": "ps-guard-max",
  "created": 1756684800,
  "results": [
    {
      "severity": "high",
      "confidence": 0.91,
      "summary": "A service account authenticated from two geographically distant IPs within a short window and escalated privileges on a database host.",
      "indicators": [
        { "type": "ip", "value": "203.0.113.41", "confidence": 0.93 },
        { "type": "process", "value": "sudo -i", "confidence": 0.89 }
      ],
      "ttps": ["T1078", "T1105", "T1548"],
      "recommended_actions": ["revoke the service account", "isolate db-prod-01", "review EDR telemetry for lateral movement"]
    }
  ]
}

POST /v1/documents/parse

Extracts structured JSON from scanned documents and PDFs with ps-parse-pro. Fields, tables, checkboxes and signatures are returned with confidence scores and source coordinates.

Field	Type	Required	Description
model	string	yes	Must be ps-parse-pro
file_url	string	conditional	HTTPS URL of the PDF or image
file	string	conditional	Base64-encoded document, alternative to file_url
template	string	no	mykad, invoice, passport, or generic
pages	string	no	Page range, e.g. 1-3, up to 20 pages
output_format	string	no	json (default) or text

request.sh

curl https://api.parrotsight.com/v1/documents/parse \
  -H "Authorization: Bearer $PS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ps-parse-pro",
    "file_url": "https://assets.parrotsight.com/samples/invoice-2026-00417.pdf",
    "template": "invoice"
  }'

Document parse response

response.json

{
  "id": "req_doc_7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a",
  "model": "ps-parse-pro",
  "created": 1756684800,
  "type": "invoice",
  "fields": {
    "invoice_number": "INV-2026-00417",
    "issue_date": "2026-08-30",
    "vendor": "Maju Teknologi Sdn. Bhd.",
    "total_amount": { "value": 1840.0, "currency": "MYR" }
  },
  "tables": [
    {
      "page": 1,
      "rows": [
        ["Item", "Qty", "Unit price"],
        ["Serial console cable", "2", "120.00"],
        ["Rack-mount shelf", "1", "1600.00"]
      ]
    }
  ],
  "confidence": 0.94,
  "usage": { "pages": 1 }
}

POST /v1/embeddings

Produces 1024-dimension dense vectors with ps-embed-base for retrieval, clustering and semantic deduplication across English, Bahasa Malaysia and Chinese.

Field	Type	Required	Description
model	string	yes	Must be ps-embed-base
input	string \| array	yes	Single text or array of up to 96 inputs
task	string	no	query or document (asymmetric retrieval)
encoding_format	string	no	float (default) or base64

request.sh

curl https://api.parrotsight.com/v1/embeddings \
  -H "Authorization: Bearer $PS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ps-embed-base",
    "input": [
      "Cara memperbaharui lesen perniagaan",
      "How to renew a business licence"
    ],
    "task": "document"
  }'

Embeddings response

response.json

{
  "object": "list",
  "model": "ps-embed-base",
  "data": [
    {
      "index": 0,
      "object": "embedding",
      "embedding": [0.0123, -0.0456, 0.0789]
    },
    {
      "index": 1,
      "object": "embedding",
      "embedding": [0.0101, -0.0432, 0.0741]
    }
  ],
  "usage": { "prompt_tokens": 16, "total_tokens": 16 }
}

GET /v1/models

Lists the models available to the key. The response is filtered by plan and key scope, so the same query may return a different set depending on the credential in use.

request.sh

curl https://api.parrotsight.com/v1/models \
  -H "Authorization: Bearer $PS_API_KEY"

Model list response

response.json

{
  "object": "list",
  "data": [
    { "id": "ps-vision-pro", "object": "model", "created": 1743000000, "owned_by": "parrotsight", "status": "stable" },
    { "id": "ps-guard-max", "object": "model", "created": 1745000000, "owned_by": "parrotsight", "status": "stable" },
    { "id": "ps-shield-base", "object": "model", "created": 1741000000, "owned_by": "parrotsight", "status": "stable" },
    { "id": "ps-parse-pro", "object": "model", "created": 1744000000, "owned_by": "parrotsight", "status": "stable" },
    { "id": "ps-lingua-7b", "object": "model", "created": 1753000000, "owned_by": "parrotsight", "status": "beta" },
    { "id": "ps-embed-base", "object": "model", "created": 1742000000, "owned_by": "parrotsight", "status": "stable" }
  ]
}

Error responses

Any 4xx or 5xx reply follows the standard error envelope described in the Error Handling reference, so failed requests can be triaged with the same parser as successful ones.

Error Handling — the full status-code table and recommended recovery for each failure.
Rate limits — how the 429 rate_limit_error code relates to plan limits and concurrency.

Was this helpful?

Your feedback shapes how we improve this documentation.

YesNo