Agent Search API¶

Programmatic search across knowledge bases, documents, and external sources — designed for both human users and autonomous AI agents.

Overview¶

The Agent Search API provides three layers of search capability:

Knowledge Base Search — Vector similarity search over user-uploaded documents
Platform Knowledge Search — Query curated AWS and technical knowledge bases
External Discovery — Google "People Also Ask" extraction and intent classification

All search endpoints require Authorization: Bearer YOUR_API_KEY authentication.

Base URL: https://api.vell.ai/api

General Search¶

Full-text search across templates, documents, chat history, and workbooks.

POST /general/search

Request Body¶

Parameter	Type	Required	Description
`search`	string	No	Search keyword

Response¶

{
  "template_search": [
    {
      "id": 1,
      "title": "Blog Post Generator",
      "description": "Generate SEO-optimized blog posts"
    }
  ],
  "workbook_search": [
    {
      "id": 456,
      "title": "Q4 Campaign Brief",
      "output": "...",
      "created_at": "2025-12-01T10:00:00Z"
    }
  ],
  "ai_chat_search": [
    {
      "id": 10,
      "name": "Content Strategy",
      "category_id": 3
    }
  ],
  "ai_chat_history_search": [
    {
      "id": 789,
      "input": "How should we position...",
      "output": "Based on competitive analysis..."
    }
  ],
  "result": ""
}

Note

Returns "result": "null" when no results are found across any index.

Agent Capability Search¶

Agents execute search through the capability system. Each search capability can be tested via the audit API or invoked autonomously during agent execution.

Test a Search Capability¶

POST /agents/audit/capabilities/{capability}/test

Path Parameters:

Parameter	Type	Description
`capability`	string	Capability slug, snake_case (e.g., `query_knowledge_base`)

Request Body: Varies by capability (see sections below).

Knowledge Base Search¶

Vector similarity search over user-uploaded documents (PDFs, text files). Uses OpenAI text-embedding-3-small embeddings with cosine similarity scoring.

Capability: QueryKnowledgeBaseCapability Slug: query_knowledge_base Cost: 2 credits per query

Parameters¶

Parameter	Type	Required	Default	Description
`query`	string	Yes	—	Search text to match against documents
`category`	string	No	`null`	Filter results by document category
`top_results`	integer	No	`5`	Number of results to return
`min_similarity`	float	No	`0.7`	Minimum cosine similarity threshold (0–1)

Request Example¶

{
  "query": "AWS pricing model for SaaS marketplace",
  "category": "aws-guides",
  "top_results": 5,
  "min_similarity": 0.7
}

Response¶

{
  "success": true,
  "results": [
    {
      "id": 1234,
      "content": "AWS Marketplace supports three pricing models for SaaS products...",
      "similarity": 0.92,
      "source_file": "aws-marketplace-guide.pdf",
      "category": "aws-guides",
      "created_at": "2025-06-15T08:30:00Z"
    },
    {
      "id": 1235,
      "content": "When configuring contract pricing, sellers can define...",
      "similarity": 0.85,
      "source_file": "pricing-playbook.pdf",
      "category": "aws-guides",
      "created_at": "2025-07-01T14:00:00Z"
    }
  ],
  "query": "AWS pricing model for SaaS marketplace",
  "provider": "openai",
  "context_found": true,
  "num_results": 2,
  "category_filter": "aws-guides",
  "credits_used": 2
}

Response Fields¶

Field	Type	Description
`results[].id`	integer	Document chunk ID
`results[].content`	string	Matched text content
`results[].similarity`	float	Cosine similarity score (0–1)
`results[].source_file`	string	Original filename
`results[].category`	string	Document category
`provider`	string	`openai` or `bedrock` — which embedding provider was used
`context_found`	boolean	Whether any results met the similarity threshold
`credits_used`	integer	Credits consumed by this query

How It Works¶

sequenceDiagram
    participant Agent
    participant Capability
    participant EmbeddingAPI as OpenAI Embeddings
    participant DB as pdf_data Table

    Agent->>Capability: execute(query, params)
    Capability->>EmbeddingAPI: Embed query (text-embedding-3-small)
    EmbeddingAPI-->>Capability: Query vector (1536 dims)
    Capability->>DB: Fetch document vectors (filtered by user/team)
    DB-->>Capability: Document vectors + metadata
    Capability->>Capability: Cosine similarity calculation
    Capability->>Capability: Filter by min_similarity, sort desc
    Capability-->>Agent: Ranked results

Access Control¶

Documents are scoped to the authenticated user's user_id
Team-shared documents (is_team_shared = true) are included when the user belongs to a team
Category filtering is applied post-retrieval

Platform Knowledge Search¶

Query curated platform knowledge bases hosted on AWS Bedrock. Supports multiple knowledge bases per capability with priority ordering and score aggregation.

Capability: QueryPlatformKnowledgeCapability Slug: query_platform_knowledge Cost: 2 credits per query

Parameters¶

Parameter	Type	Required	Default	Description
`query`	string	Yes	—	Search text
`top_results`	integer	No	`5`	Number of results to return
`min_similarity`	float	No	`0.5`	Minimum score threshold (0–1)
`category`	string	No	`null`	Filter by knowledge base category

Request Example¶

{
  "query": "How to configure IAM roles for cross-account access",
  "top_results": 3,
  "min_similarity": 0.6
}

Response¶

{
  "success": true,
  "results": [
    {
      "content": "To configure cross-account IAM roles, create a trust policy...",
      "score": 0.88,
      "source_kb": "AWS Security Best Practices",
      "source_kb_id": "KB-AWS-SEC-001",
      "source_category": "security",
      "source_file": "iam-cross-account.pdf"
    }
  ],
  "query": "How to configure IAM roles for cross-account access",
  "platform_kb": true,
  "knowledge_bases_queried": [
    {
      "id": "KB-AWS-SEC-001",
      "name": "AWS Security Best Practices",
      "results": 1
    },
    {
      "id": "KB-AWS-GEN-002",
      "name": "AWS General Documentation",
      "results": 0
    }
  ],
  "num_results": 1,
  "credits_used": 2
}

Response Fields¶

Field	Type	Description
`results[].score`	float	Bedrock relevance score (0–1)
`results[].source_kb`	string	Knowledge base name
`results[].source_kb_id`	string	Knowledge base identifier
`results[].source_category`	string	KB category
`knowledge_bases_queried`	array	List of KBs searched with per-KB result counts
`platform_kb`	boolean	Always `true` for platform knowledge queries

Multi-KB Query Flow¶

flowchart TD
    A[Agent Query] --> B{Capability Mappings Exist?}
    B -->|Yes| C[Load Mapped KBs with Priority]
    B -->|No| D[Fallback to Legacy Config KB ID]
    C --> E[Query Each KB in Parallel]
    D --> E
    E --> F[Aggregate Results]
    F --> G[Sort by Score Descending]
    G --> H[Apply top_results Limit]
    H --> I[Return Ranked Results]

Credential Modes¶

Platform knowledge queries support three credential modes for Bedrock access:

Mode	Description	Use Case
`platform`	Vellocity's managed AWS credentials	Default for all users
`user_keys`	User's own AWS access key + secret	Custom KB access
`user_role`	Cross-account IAM role assumption (BYOC)	Enterprise accounts

Discover Search Questions¶

Extract Google "People Also Ask" questions for a topic, with search intent classification. Useful for content planning, FAQ generation, and competitive research.

Capability: DiscoverSearchQuestionsCapability Slug: discover_search_questions Cost: 3 credits per query

Parameters¶

Parameter	Type	Required	Default	Description
`topic`	string	Yes	—	Topic to discover questions for
`include_related`	boolean	No	`true`	Include related search suggestions

Request Example¶

{
  "topic": "AWS Marketplace SaaS listing optimization",
  "include_related": true
}

Response¶

{
  "success": true,
  "data": {
    "topic": "AWS Marketplace SaaS listing optimization",
    "questions": [
      "How do I optimize my AWS Marketplace listing?",
      "What is a good SEO score for AWS Marketplace?",
      "How to increase visibility on AWS Marketplace?",
      "What are AWS Marketplace listing best practices?"
    ],
    "question_count": 4,
    "related_searches": [
      "aws marketplace listing requirements",
      "aws marketplace seo",
      "aws marketplace product page optimization"
    ],
    "formatted_questions": [
      {
        "question": "How do I optimize my AWS Marketplace listing?",
        "snippet": "To optimize your listing, focus on keyword-rich titles...",
        "source": "AWS Partner Network Blog",
        "link": "https://example.com/article"
      }
    ],
    "question_analysis": {
      "by_intent": {
        "informational": [
          "How do I optimize my AWS Marketplace listing?",
          "What are AWS Marketplace listing best practices?"
        ],
        "commercial": [
          "What is a good SEO score for AWS Marketplace?"
        ],
        "transactional": [],
        "navigational": [
          "How to increase visibility on AWS Marketplace?"
        ]
      },
      "summary": {
        "informational_count": 2,
        "commercial_count": 1,
        "transactional_count": 0,
        "navigational_count": 1
      },
      "primary_intent": "informational"
    }
  },
  "credits_used": 3
}

Intent Classification¶

Questions are automatically classified into four search intent categories:

Intent	Description	Example
Informational	User wants to learn something	"How do I configure..."
Commercial	User is evaluating options	"What is the best..."
Transactional	User wants to take action	"Buy AWS support plan"
Navigational	User wants to find a specific page	"AWS Marketplace console login"

Stateful Agent Search Sessions (Dry Run)¶

For multi-turn conversational search, agents use dry-run sessions. These sessions maintain context across messages, allowing agents to iteratively refine searches and build on previous results.

Start a Session¶

POST /dry-run/sessions/start

Request Body:

Parameter	Type	Required	Default	Description
`entity_type`	string	Yes	—	Entity type: `ai_presentation`, `ai_proposal`, `ai_cosell`
`entity_id`	integer	Yes	—	Entity ID to provide context
`persona`	string	No	`buyer`	Agent persona to use
`use_bedrock_memory`	boolean	No	`false`	Enable cross-session memory
`quality`	string	No	`standard`	Response quality: `quick`, `standard`, `detailed`

Response:

{
  "success": true,
  "session": {
    "token": "drs_abc123def456",
    "persona": "buyer",
    "expires_at": "2025-12-01T12:00:00Z",
    "messages": [
      {
        "role": "assistant",
        "content": "I'm ready to help you explore this listing..."
      }
    ],
    "message_count": 1
  }
}

Send a Message (Query)¶

POST /dry-run/sessions/{token}/message

Request Body:

Parameter	Type	Required	Max Length	Description
`message`	string	Yes	10,000 chars	User message or search query

Response:

{
  "success": true,
  "response": "Based on the knowledge base, AWS Marketplace pricing supports...",
  "metadata": {
    "model": "claude-3-sonnet",
    "knowledge_sources_used": ["user-kb", "platform-kb"],
    "tokens_used": 1250
  },
  "session": {
    "token": "drs_abc123def456",
    "persona": "buyer",
    "message_count": 3
  }
}

Other Session Operations¶

Endpoint	Method	Description
`/dry-run/sessions`	GET	List active sessions (max 20)
`/dry-run/sessions/{token}`	GET	Get session details and context
`/dry-run/sessions/{token}/persona`	PUT	Switch agent persona mid-session
`/dry-run/sessions/{token}/reset`	POST	Reset session state (clears messages)
`/dry-run/sessions/{token}/end`	POST	End and clean up session

Session Lifecycle¶

stateDiagram-v2
    [*] --> Active: POST /start
    Active --> Active: POST /message
    Active --> Active: PUT /persona
    Active --> Active: POST /reset
    Active --> Ended: POST /end
    Active --> Expired: TTL exceeded
    Ended --> [*]
    Expired --> [*]

Additional Search Capabilities¶

These capabilities are invoked through the same POST /agents/audit/capabilities/{capability}/test endpoint shown above. Slugs are snake_case and must match the capability registry exactly. Credit costs are sourced from CapabilityRegistry::bootstrapDefaults().

Capability	Slug	Cost	Data Source	Description
Slack Knowledge Source	`slack_knowledge_source`	5	Slack workspace	Ingest Slack channel content into Bedrock knowledge bases for AI retrieval
LinkedIn Ad Intelligence	`linkedin_ad_intelligence`	10	LinkedIn Ad Library API	Pull live competitor ads and run a Claude-powered messaging teardown
Keyword Research	`keyword_research`	5	Serper API	Real-time search volumes and buyer-intent signals
Competitive Intelligence & Analysis	`competitor_analysis`	12	Multiple	Competitor content tracking and counter-positioning
Content Gap Analysis	`content_gap_analysis`	15	Multiple	Keywords competitors rank for but you don't
SEO Intelligence	`seo_intelligence`	10	DataForSEO	Traffic, keywords, tech stack, competitor positioning
Co-Sell Partner Discovery & Matching	`cosell_partner_matching`	20	Partner data	AI-scored partner matches across ICP overlap, product fit, market alignment

Vector Storage Providers¶

The platform supports three vector storage backends:

OpenAI Embeddings (Default)¶

Model: text-embedding-3-small
Dimensions: 1,536
Storage: pdf_data.vector column (JSON)
Similarity: Cosine distance (calculated in PHP)

AWS Bedrock Knowledge Base¶

Embeddings: Amazon Titan or configured model
Storage: AWS-managed vector index
Similarity: Native Bedrock retrieval
Features: Metadata filtering, hybrid search

AWS S3 Vectors¶

Dimensions: 1,024 (configurable)
Distance Metric: Cosine
Data Type: Float32
Batch Limit: 100 vectors per request
FTR Compliant: All data stays in AWS

Error Responses¶

All search endpoints return consistent error formats:

{
  "success": false,
  "error": "Knowledge base not found",
  "message": "No documents available for search. Upload documents first."
}

Common Error Codes¶

HTTP Status	Error	Cause
401	Unauthorized	Invalid or missing API key
403	Forbidden	User lacks access to the requested knowledge base
404	Not Found	Knowledge base or session token not found
422	Validation Error	Missing required `query` parameter
429	Rate Limited	Too many search requests
500	Provider Error	Bedrock or OpenAI API failure

Rate Limits¶

Search endpoints route through the default api rate limiter (60 requests/minute per user, regardless of plan tier).

The Partner API limiter (partner) — used by 3PI partner keys for Partner-API endpoints, not for the agent search endpoints documented here — is tier-based:

Plan	Requests/Minute	Requests/Hour
Starter	60	1,200
Accelerate	100	2,000
Command	1,000	20,000

Source: App\Providers\RouteServiceProvider::configureRateLimiting().

Credit Costs¶

Credit costs match CapabilityRegistry::bootstrapDefaults(). Slugs are snake_case.

Capability	Slug	Credits
Query Knowledge Base	`query_knowledge_base`	2
Query Platform Knowledge	`query_platform_knowledge`	2
Discover Search Questions	`discover_search_questions`	3
Keyword Research	`keyword_research`	5
Slack Knowledge Source	`slack_knowledge_source`	5
SEO Content Analysis	`seo_content_analysis`	8
LinkedIn Ad Intelligence	`linkedin_ad_intelligence`	10
SEO Intelligence	`seo_intelligence`	10
Competitive Intelligence & Analysis	`competitor_analysis`	12
Content Gap Analysis	`content_gap_analysis`	15
Co-Sell Partner Discovery & Matching	`cosell_partner_matching`	20
Dry-run session message	(varies by model)	—