How do I add live web search to an AI agent?

Call Prismfy's POST /v1/search endpoint from your agent loop, then pass the returned structured JSON results into your prompt, tool handler, or workflow step.

Is Prismfy synchronous or async?

Prismfy's main web search API is synchronous. The response returns when search results are ready, or immediately when the query is served from cache.

What does POST /v1/search return?

POST /v1/search returns structured JSON with results, cached status, the original query, and metadata such as engines used, duration, and paging information.

Can I use Prismfy with MCP or coding agents?

Yes. Prismfy is designed to fit tool-calling workflows, MCP integrations, coding agents, research agents, and docs verification flows that need live public-web context.

Web Search API for AI Agents

Introduction

Prismfy gives AI agents and automated workflows synchronous public-web search through one REST endpoint: POST /v1/search.

⚡

Single endpoint

POST /v1/search — that's it

🧰

Structured JSON responses

Title, URL, snippet, engine, and metadata for tool calling

🔄

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 when created. Store it securely, because the full secret is not recoverable later.

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 supported engines

ℹ️Billing is per API request in the current shared-balance model. One POST /v1/search call consumes one request when it is uncached, regardless of which engines you query. Cache hits are free.

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": ["brave", "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: `["brave", "bing"]`. Free: `brave`, `bing` (default) — all engines are accepted, including Google. Free accounts are limited to 10 RPM overall, and some engines may apply stricter sub-limits. Live engine catalog: call `GET /v1/plans` to inspect the current `allEngines`, `defaultEngines`, and `allowedEngines` values for your environment.
`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 response includes a reduced meta object with request-shape fields only; execution fields like taskId, durationMs, and provider are omitted.

json

{
  "results": [
    {
      "title": "TypeScript Best Practices 2026",
      "url": "https://example.com/typescript",
      "content": "A short snippet of the page content...",
      "engine": "brave"
    }
  ],
  "cached": false,
  "query": "typescript best practices",
  "meta": {
    "taskId": "550e8400-e29b-41d4-a716-446655440000",
    "durationMs": 1243,
    "provider": "prismfy",
    "engines": ["brave", "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
`cached`	boolean	true = served from cache (no charge)
`meta.taskId`	string	Unique search task ID. Omitted when cached.
`meta.durationMs`	number	Milliseconds the search took. Omitted when cached.
`meta.provider`	string	Provider label when execution metadata is present. Omitted when cached.

Plan Limits

Plan	page max	RPM	Quota	Default engines
Free	1	10	1,000 one-time requests	brave, bing
Pro	10	60	3,500 requests / mo	brave, bing
Data Digger	10	120	10,000 requests / mo	brave, bing
Enterprise	20	300	Custom	all engines

GET /v1/user/me

Returns the full user profile including the current shared request balance and quota usage. Use this to display plan and usage state in the dashboard.

GET

/v1/user/me

Full profile + quota

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "tier": "free",
  "balance": {
    "shared": {
      "remaining": 953,
      "expiresAt": null,
      "expired": false
    }
  },
  "quota": {
    "total": 1000,
    "used": 47,
    "remaining": 953,
    "expiresAt": null,
    "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": ["brave", "bing"],
      "status": "success",
      "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 current balance status
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
Pro	60 requests / minute
Data Digger	120 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

Introduction

Prismfy gives AI agents and automated workflows synchronous public-web search through one REST endpoint: POST /v1/search.

⚡

Single endpoint

POST /v1/search — that's it

🧰

Structured JSON responses

Title, URL, snippet, engine, and metadata for tool calling

🔄

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 when created. Store it securely, because the full secret is not recoverable later.

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 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": ["brave", "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: `["brave", "bing"]`. Free: `brave`, `bing` (default) — all engines are accepted, including Google. Free accounts are limited to 10 RPM overall, and some engines may apply stricter sub-limits. Live engine catalog: call `GET /v1/plans` to inspect the current `allEngines`, `defaultEngines`, and `allowedEngines` values for your environment.
`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

json

{
  "results": [
    {
      "title": "TypeScript Best Practices 2026",
      "url": "https://example.com/typescript",
      "content": "A short snippet of the page content...",
      "engine": "brave"
    }
  ],
  "cached": false,
  "query": "typescript best practices",
  "meta": {
    "taskId": "550e8400-e29b-41d4-a716-446655440000",
    "durationMs": 1243,
    "provider": "prismfy",
    "engines": ["brave", "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
`cached`	boolean	true = served from cache (no charge)
`meta.taskId`	string	Unique search task ID. Omitted when cached.
`meta.durationMs`	number	Milliseconds the search took. Omitted when cached.
`meta.provider`	string	Provider label when execution metadata is present. Omitted when cached.

Plan Limits

Plan	page max	RPM	Quota	Default engines
Free	1	10	1,000 one-time requests	brave, bing
Pro	10	60	3,500 requests / mo	brave, bing
Data Digger	10	120	10,000 requests / mo	brave, bing
Enterprise	20	300	Custom	all engines

GET /v1/user/me

Returns the full user profile including the current shared request balance and quota usage. Use this to display plan and usage state in the dashboard.

GET

/v1/user/me

Full profile + quota

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "tier": "free",
  "balance": {
    "shared": {
      "remaining": 953,
      "expiresAt": null,
      "expired": false
    }
  },
  "quota": {
    "total": 1000,
    "used": 47,
    "remaining": 953,
    "expiresAt": null,
    "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": ["brave", "bing"],
      "status": "success",
      "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 current balance status
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
Pro	60 requests / minute
Data Digger	120 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