Prismfy — Web Search API

Introduction

Prismfy provides a simple, powerful REST API to search the web — powered by 15 engines including Google, Bing, Reddit, GitHub, arXiv and more — without managing proxies, CAPTCHAs, or infrastructure. One endpoint, clean results, predictable pricing.

⚡

Single endpoint

POST /v1/search — that's it

💰

$3 / 1,000 queries

Pay only for what you use

🔄

Cached results free

Cache hits don't count against quota

Base URL

https://api.prismfy.io

All requests must be made over HTTPS. HTTP requests will be rejected. The API returns JSON for all responses.

Quick Start

Get your first search results in under a minute:

Create an account

Copy your API key

Your key is shown once on registration. Find it again in the Dashboard → API Keys.

Make your first request

Use any HTTP client. The key goes in the Authorization header.

cURL

# Step 1 — Sign up and grab your API key from the dashboard
# Step 2 — Make your first search request:

curl -X POST https://api.prismfy.io/v1/search \
  -H "Authorization: Bearer ss_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "hello world"}'

Authentication

All protected endpoints require an Authorization header:

http

Authorization: Bearer <token>

Using an API key

The simplest auth method for server-side code. Keys start with ss_live_ and don't expire unless you delete them.

bash

curl https://api.prismfy.io/v1/search \
  -H "Authorization: Bearer ss_live_YOUR_KEY" \
  ...

POST /v1/search

The primary endpoint. Synchronous — the response returns when results are ready. If the same query was cached, it responds instantly with cached: true and no quota is deducted.

POST

/v1/search

Execute a search across one or more of the 15 supported engines

cURL

curl -X POST https://api.prismfy.io/v1/search \
  -H "Authorization: Bearer ss_live_••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "typescript best practices",
    "engines": ["google", "bing"],
    "language": "en",
    "page": 1
  }'

Request Parameters

Field	Type	Required	Description
`query`	string	✅	Search query. 1–500 characters.
`page`	number	—	Results page (default: 1). Max depends on plan.
`engines`	string[]	—	Engine(s) to query. Default: `["google", "bing"]`. Free: only `google` & `bing`. PAYG / Data Digger / Enterprise — all 15 engines: • web: `google`, `bing`, `brave`, `yahoo` • news: `yahoo news`, `hackernews` • code: `github`, `pypi`, `mdn` • academic: `arxiv`, `pubmed` • AI: `huggingface` • community: `reddit` • reference: `wikipedia` • Q&A: `askubuntu`
`language`	string	—	Language code, e.g. `en`, `ru`, `de`.
`timeRange`	string	—	`day` / `week` / `month` / `year`
`domain`	string	—	Restrict to a domain — adds `site:domain` to the query.

Response Format

A successful response always includes results and cached. When cached is true, the meta.taskId and meta.durationMs fields are omitted.

json

{
  "results": [
    {
      "title": "TypeScript Best Practices 2026",
      "url": "https://example.com/typescript",
      "content": "A short snippet of the page content...",
      "engine": "google",
      "score": 0.95
    }
  ],
  "cached": false,
  "query": "typescript best practices",
  "meta": {
    "taskId": "tsk_abc123",
    "durationMs": 1243,
    "provider": "searxng",
    "engines": ["google", "bing"],
    "page": 1,
    "language": "en",
    "timeRange": "month",
    "domain": null
  }
}

Field	Type	Description
`results[].title`	string	Page title
`results[].url`	string	Canonical URL
`results[].content`	string	Short snippet of page text
`results[].engine`	string	Which engine returned this result
`results[].score`	number	Relevance score 0–1
`cached`	boolean	true = served from cache (no charge)
`meta.taskId`	string \| null	Unique search task ID (null if cached)
`meta.durationMs`	number \| null	Milliseconds the search took (null if cached)
`meta.provider`	string \| null	Search provider used (e.g. "searxng"). null if cached.

Plan Limits

Plan	page max	RPM	Quota	Engines
Free	1	10	3,000 / month	google, bing
Pay As You Go	5	60	Credit-based ($3 / 1k)	all 15
Data Digger	10	60	10,000 / month + $2.5 / extra 1k	all 15
Enterprise	20	300	Unlimited	all 15

GET /v1/user/me

Returns the full user profile including current quota usage. Use this to display quota rings and plan info in the dashboard.

GET

/v1/user/me

Full profile + quota

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "tier": "free",
  "quota": {
    "total": 3000,
    "used": 47,
    "remaining": 2953,
    "expiresAt": "2026-04-04T16:27:53.678Z",
    "expired": false
  },
  "isActive": true,
  "createdAt": "2026-03-05T16:27:53.678Z"
}

GET /v1/user/me/searches

Paginated list of the user's recent search queries. Useful for the "Recent Queries" dashboard widget.

GET

/v1/user/me/searches

Paginated search history

Query param	Default	Max	Description
`limit`	20	100	Number of results to return
`offset`	0	100,000	Skip this many records (pagination)

json

{
  "searches": [
    {
      "id": "uuid",
      "taskId": "uuid",
      "query": "best typescript frameworks 2026",
      "engines": ["google", "bing"],
      "status": "completed",
      "durationMs": 1243,
      "createdAt": "2026-03-05T14:23:11.000Z"
    }
  ],
  "limit": 20,
  "offset": 0
}

GET /v1/user/me/usage

Event log: quota deductions, plan upgrades, admin adjustments.

GET

/v1/user/me/usage

Quota event log

Event	When
`request_used`	A successful search — quota deducted
`quota_set`	Quota manually changed (upgrade, admin)

API Keys

Each user can have up to 10 API keys. Key values are shown only once — at creation time. After that, only metadata (name, last used) is available.

List Keys

GET

/v1/user/me/keys

Returns all keys (metadata only, no raw values)

json

{
  "keys": [
    {
      "id": "uuid",
      "name": "Default",
      "lastUsedAt": "2026-03-05T14:23:11.000Z",
      "expiresAt": null
    },
    {
      "id": "uuid",
      "name": "Production Server",
      "lastUsedAt": "2026-03-04T09:00:00.000Z",
      "expiresAt": null
    }
  ]
}

Create a Key

POST

/v1/user/me/keys

Creates a new key — raw value is shown only in this response

json

// Request
{ "name": "Production Server" }

// Response 201
{
  "id": "uuid",
  "name": "Production Server",
  "key": "ss_live_a1b2c3d4...",
  "expiresAt": null
}

⚠️The key field is returned only in this response. Store it securely — you cannot retrieve it again. To rotate a key, create a new one and delete the old one.

Delete a Key

DELETE

/v1/user/me/keys/:id

Permanently deletes and immediately invalidates the key

json

// Response 200
{ "success": true }

// Response 404 — key not found or belongs to another user
{ "error": "Not found", "code": "NOT_FOUND" }

ℹ️Deletion is immediate — the key is removed from the cache within milliseconds. Any in-flight requests using the deleted key will be rejected.

Key Rotation

Rotate keys regularly to limit exposure. The safe rotation pattern:

cURL

# 1. Create a new key
curl -X POST https://api.prismfy.io/v1/user/me/keys \
  -H "Authorization: Bearer ss_live_OLD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production v2"}'

# 2. Copy the key from the response (only shown once)
# 3. Delete the old key
curl -X DELETE https://api.prismfy.io/v1/user/me/keys/KEY_ID \
  -H "Authorization: Bearer ss_live_OLD_KEY"

Error Handling

All errors return a consistent JSON structure:

json

{
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE"
}

Error Codes

HTTP	code	Cause	What to do
400	`VALIDATION_ERROR`	Invalid request body	Show the error message to the user
400	`INVALID_JSON`	Empty body or malformed JSON	Check Content-Type: application/json
400	`INVALID_ENGINES`	All requested engines are disallowed on your tier	Check `allowedEngines` array in the error response
401	`UNAUTHORIZED`	Missing, expired, or invalid token	Redirect to login
402	`PAYMENT_REQUIRED`	Quota exhausted or expired	Show upgrade prompt or reset date
404	`NOT_FOUND`	Resource not found	Show 404 message
429	`RATE_LIMIT_EXCEEDED`	Too many requests	Wait retryAfter seconds
504	`TIMEOUT`	Search took > 30 seconds	Retry the request
500	`INTERNAL_ERROR`	Server error	Show generic error message

Rate Limiting

When rate-limited, the response includes a retryAfter field (seconds) and a Retry-After HTTP header:

json

{
  "error": "Too many requests",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 47
}

Plan	Rate limit
Free	10 requests / minute
Pay As You Go	60 requests / minute
Data Digger	60 requests / minute
Enterprise	300 requests / minute

Quick Reference

BASE URL  https://api.prismfy.io

── Public ────────────────────────────────────
GET  /v1/plans                Plans & limits

── Search ────────────────────────────────────
POST /v1/search               Execute a search

── User ──────────────────────────────────────
GET  /v1/user/me              Profile + quota
GET  /v1/user/me/searches     Search history
GET  /v1/user/me/usage        Quota event log
GET  /v1/user/me/keys         List API keys
POST /v1/user/me/keys         Create API key
DEL  /v1/user/me/keys/:id     Delete API key

Get API Key →View Pricing