pixserp

A first call in under a minute. Point the SDK athttps://pixserp.com/api/v1, send a user message, get back an answer with inline[1]citations and a structuredmessage.citationsarray.
- Create an API keyfrom your dashboard.
- Install the OpenAI SDK for your language (or skip and curl).
- Run the snippet below.

from openai import OpenAI client = OpenAI( api_key="pxs_…", base_url="https://pixserp.com/api/v1", ) r = client.chat.completions.create( model="pixserp-fast", messages=[{"role": "user", "content": "NYC congestion pricing 2026 update"}], ) print(r.choices[0].message.content) print(r.choices[0].message.citations)

Heads up:new accounts start with$2.50of free credit. The first call charges$0.0025against that balance — no card required to start.

Pass your key asAuthorization: Bearer <key>— the standard OpenAI header. The legacyX-API-KEYheader is also accepted for backwards compatibility.

Authorization: Bearer pxs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

- Keys are 40-hex-char secrets, displayed once at creation. Store them in env vars or a secrets manager — never commit to git or ship to client-side code.
- Rotate or revoke fromyour dashboardany time.
- We store only a SHA-256 hash on our end. If you lose the secret, generate a new one.

r = client.chat.completions.create( model="pixserp-agent", messages=[{"role": "user", "content": "What's driving NYC office vacancy in 2026 and which neighborhoods are bouncing back?"}], extra_body={"max_steps": 30}, ) print(r.choices[0].message.content) print(r.choices[0].message.citations)

POST https://pixserp.com/api/v1/chat/completions— the OpenAI Chat Completions API.

Standard OpenAI shape, withmessage.citationsas a pixserp extension carrying the structured cards behind the inline[n]markers.

{ "id": "chatcmpl-…", "object": "chat.completion", "created": 1746576000, "model": "pixserp-fast", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "NYC congestion pricing took effect Jan 5, 2025 [1]…", "citations": [ {"id": "1", "kind": "web", "url": "https://digital-strategy.ec.europa.eu/…", "title": "Regulatory framework for AI", "snippet": "…"}, {"id": "3", "kind": "news", "url": "https://reuters.com/…", "title": "…"} ] }, "finish_reason": "stop" } ], "usage": {"prompt_tokens": 412, "completion_tokens": 187, "total_tokens": 599} }

Useful response headers:x-cost-usd,x-pixserp-tool-calls,x-ratelimit-remaining,x-ratelimit-reset.

POST https://pixserp.com/api/v1/responses— OpenAI's newer single-turn pattern. Pick this if your codebase has migrated toclient.responses.create(); otherwise/chat/completionsis the more familiar surface.

r = client.responses.create( model="pixserp-fast", input="Summarize the latest CRISPR developments", ) print(r.output_text) # Citations as Responses-API url_citation annotations for ann in r.output[0].content[0].annotations: print(ann["url"], ann["title"])

Setstream: trueto receive answer tokens as they're generated. The SSE wire is OpenAI-standard: eachdata:line carries achat.completion.chunk, terminated bydata: [DONE].

stream = client.chat.completions.create( model="pixserp-fast", messages=[{"role": "user", "content": "Top-rated ramen near East Village, NYC"}], stream=True, ) for chunk in stream: delta = chunk.choices[0].delta if delta.content: print(delta.content, end="", flush=True) # Citations land on a final delta as a structured array if getattr(delta, "citations", None): for c in delta.citations: print(c["url"])

Citations arrive on the final delta chunk before thefinish_reason: "stop"chunk — accumulate them as the stream completes.

When streaming withpixserp-agent, setextra_body={"pixserp_emit_progress": true}to receive loop-progress events inline ondelta.pixserp_event. Standard OpenAI clients ignore unknown delta fields, so this is safe to enable. Useful for rendering a live trace of the agent's reasoning.

reasonvalues:orchestrator_done(model decided),no_new_domains(anti-loop bail),step_cap(hitmax_steps),no_next_query(orchestrator returned no follow-up).

Every fact in the answer is grounded to a result the agent fetched. Citations live in two complementary places:

- Inline markersin the prose:[1],[2], etc. — Perplexity-style, placed immediately after the fact they support.
- Structured arrayon the message:

- Chat Completions →message.citations

- Responses API →output[0].content[0].annotations(each is aurl_citationwithstart_index/end_indexpinning it to the span in the text)

Each citation entry carries akind(web,news,place,shopping,flight,hotel,video,transcript,image,webpage) plus per-kind structured fields — rating, price, hours, GPS, etc. — so renderers can show rich cards instead of bare links.

// One element from message.citations { "id": "1", "kind": "place", "title": "Ippudo NY", "rating": 4.5, "address":"65 4th Ave, New York, NY 10003", "url": "https://www.google.com/maps/place/…", "markdown": "Ippudo NY — 4.5★ · 65 4th Ave · New York" }

Passresponse_formatwith a JSON schema and the agent fills it with web-grounded values. Drop straight into typed code without parsing or validation gymnastics.

r = client.chat.completions.create( model="pixserp-fast", messages=[{"role": "user", "content": "Top 3 aerospace companies, CEO, founded year"}], response_format={ "type": "json_schema", "json_schema": { "name": "companies", "schema": { "type": "object", "properties": { "companies": { "type": "array", "items": { "type": "object", "properties": { "name": {"type": "string"}, "ceo": {"type": "string"}, "founded_year": {"type": "integer"}, }, "required": ["name", "ceo", "founded_year"], }, }, }, "required": ["companies"], }, }, }, ) import json data = json.loads(r.choices[0].message.content) for c in data["companies"]: print(c["name"], "-", c["ceo"], "-", c["founded_year"])

Whenresponse_formatis set, the answer comes back as JSON only — no prose, no markdown fences. The agent searches the web first, then formats its findings into your schema.

{ "error": { "message": "Invalid or missing API key. Pass it as Authorization: Bearer <key>.", "type": "authentication_error", "code": "invalid_api_key", "param": null } }

Per-second cap, scaled by trailing 30-day spend. New accounts start at the lowest tier (Tier 1, 5 RPS) and step up automatically as payments land.

Every response carries the live state in headers:

x-ratelimit-tier: Tier 2 x-ratelimit-limit: 15 x-ratelimit-remaining: 12 x-ratelimit-reset: 1746576042

Need a higher cap fast? Email[](https://pixserp.com/cdn-cgi/l/email-protection#b9caccc9c9d6cbcdf9c9d0c1cadccbc997dad6d4)<<<[email protected]with your use case.

The same pipeline that powers/chat/completions— same answers, same citations, same billing. No new endpoint to learn if you already use pixserp via the OpenAI SDK; just a different transport for clients that speak MCP instead of REST.

Paste the snippet for your client, replace the API key, restart. pixserp appears as a tool namedsearch.

// ~/Library/Application Support/Claude/claude_desktop_config.json // (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) { "mcpServers": { "pixserp": { "command": "npx", "args": [ "-y", "mcp-remote", "https://pixserp.com/api/v1/mcp", "--header", "Authorization: Bearer pxs_…" ] } } }

Single tool exposed today. Schema is advertised viatools/list— clients pick it up automatically.

Tool result shape (returned in thetools/callresponse):

{ "content": [ { "type": "text", "text": "NYC congestion pricing took effect Jan 5, 2025 [1]…\n\nSources:\n[1] MTA — https://new.mta.info/…" } ], "structuredContent": { "answer": "NYC congestion pricing took effect …", "citations": [ { "id": "1", "kind": "news", "url": "https://reuters.com/…", "title": "…" } ], "model": "pixserp-fast", "cost_usd": 0.0015 }, "isError": false }

- Same API key as the REST endpoints —Authorization: Bearer pxs_….
- Eachtools/callbills as achat.completionsrequest at the chosen model's price. MCP is transport, not a separate billable surface.
- Rate-limit tiers apply identically — your RPS cap is shared across REST and MCP traffic.
- Auth errors surface as JSON-RPC errors with custom codes:-32001(auth),-32002(rate-limited),-32003(insufficient quota). Search failures come back as atools/callresult withisError: trueso the calling LLM can reason about them.

Protocol version:2025-06-18. Stateless transport (no session id) — every request is independent.notifications/initializedandnotifications/cancelledare acknowledged silently.

POST https://pixserp.com/api/v1/watch— a chat completion that re-runs itself on a cron schedule and fires a webhook when the citation set changes. Same shape as/chat/completions, pluscadence+webhook. Each tick costs the same as a normal API call at the chosen model — no premium tier, no storage fee.

POST https://example.com/pixserp-webhook Content-Type: application/json X-Pixserp-Watch-Id: wch_abc123 X-Pixserp-Event: watch.tick.changed X-Pixserp-Signature: sha256=<hmac> { "watch_id": "wch_abc123", "tick_id": "wtk_xyz789", "event": "watch.tick.changed", "ticked_at": "2026-05-20T14:00:00Z", "response": { ...chat completion JSON, including citations[] }, "diff": { "added": [ {"url": "...", "kind": "hotel", "prev_label": null, "curr_label": "Park Hotel Tokyo — $230/night · ★ 4.6"} ], "removed": [], "modified": [ {"url": "https://booking.com/...", "kind": "hotel", "prev_label": "Park Hotel Tokyo — $245/night · ★ 4.6", "curr_label": "Park Hotel Tokyo — $230/night · ★ 4.6"} ] } }

What counts as a change.pixserp uses a per-type signal whitelist: for hotels, the rate and rating; for flights, the price + airline + duration; for shopping, the extracted price + title; for web/news, the title (snippet excluded — it varies between searches without representing real change); for places, the rating + reviews. Cosmetic variation (relative timestamps like "5 hours ago", snippet wording) does NOT trigger a webhook.

Signature:HMAC-SHA256(secret, raw_body)→ hex, prefixedsha256=. Verify in your handler before trusting the payload. Retry policy: 3 attempts (immediate, +60s, +10min), 10s timeout each. Non-2xx = fail; all retries exhausted leaveswebhookStatus = -1on the tick row.

Each tick = one chat completion at the chosen model's flat per-request price. No markup, no storage fee, no rate-limit pool separate from your normal calls.