POST /query
The core endpoint for processing natural language queries and returning structured data results.
Base URL
https://app.snakequery.com/api/query
| Header | Value | Required |
|---|
Content-Type | application/json | Yes |
Authorization | Bearer {api_key} | Yes |
Request Body
Natural language description of what you want to find or extract from the data
Array of objects to query directly. Use this when you have data ready to analyze.
URL to fetch data from before querying. Alternative to providing data directly.
JSON schema defining the structure of the expected response for consistent, typed results.
Response
The query results formatted according to your request or schema
Token usage information for billing and monitoring
Total tokens consumed for this query
Input tokens (query, data, schema)
Output tokens (response generation)
Examples
Basic Query with Direct Data
const response = await fetch('https://app.snakequery.com/api/query', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer your_api_key_here'
},
body: JSON.stringify({
query: 'Find products under $100',
data: [
{ name: 'iPhone 14', price: 999, category: 'electronics' },
{ name: 'Coffee Mug', price: 19, category: 'home' },
{ name: 'Notebook', price: 15, category: 'office' }
]
})
});
const result = await response.json();
console.log(result.response);
{
"response": [
{ "name": "Coffee Mug", "price": 19, "category": "home" },
{ "name": "Notebook", "price": 15, "category": "office" }
],
"usageCount": {
"totalTokens": 245,
"promptTokens": 180,
"completionTokens": 65
}
}
Query External API
const response = await fetch('https://app.snakequery.com/api/query', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer your_api_key_here'
},
body: JSON.stringify({
query: 'Show the 3 cheapest products with their titles and prices',
fetchUrl: 'https://api.escuelajs.co/api/v1/products'
})
});
const result = await response.json();
console.log(result.response);
{
"response": [
{ "title": "Basic T-Shirt", "price": 15 },
{ "title": "Simple Notebook", "price": 18 },
{ "title": "Coffee Mug", "price": 22 }
],
"usageCount": {
"totalTokens": 420,
"promptTokens": 310,
"completionTokens": 110
}
}
Structured Response with Schema
const productSchema = {
type: 'array',
items: {
type: 'object',
properties: {
productName: { type: 'string' },
price: { type: 'number', minimum: 0 },
category: { type: 'string' },
inStock: { type: 'boolean' }
},
required: ['productName', 'price']
}
};
const response = await fetch('https://app.snakequery.com/api/query', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer your_api_key_here'
},
body: JSON.stringify({
query: 'List all electronics products with availability status',
data: [
{ name: 'MacBook Pro', price: 2399, category: 'electronics', available: true },
{ name: 'iPad Air', price: 599, category: 'electronics', available: false },
{ name: 'Coffee Maker', price: 89, category: 'home', available: true }
],
responseSchema: productSchema
})
});
const result = await response.json();
{
"response": [
{
"productName": "MacBook Pro",
"price": 2399,
"category": "electronics",
"inStock": true
},
{
"productName": "iPad Air",
"price": 599,
"category": "electronics",
"inStock": false
}
],
"usageCount": {
"totalTokens": 380,
"promptTokens": 290,
"completionTokens": 90
}
}
Response Schemas
Response schemas ensure consistent, type-safe results by defining the exact structure of your expected response.
Schema Benefits
- Type Safety: Guarantee specific data types in responses
- Consistency: Get the same structure every time
- Validation: Automatic validation of AI-generated responses
- Performance: Faster processing with clear expectations
Common Schema Patterns
Array of Objects
{
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" },
"value": { "type": "number" }
},
"required": ["name", "value"]
}
}
Single Object
{
"type": "object",
"properties": {
"total": { "type": "number" },
"average": { "type": "number" },
"count": { "type": "integer" }
},
"required": ["total"]
}
Nested Structure
{
"type": "object",
"properties": {
"summary": {
"type": "object",
"properties": {
"totalItems": { "type": "integer" },
"categories": {
"type": "array",
"items": { "type": "string" }
}
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"name": { "type": "string" }
}
}
}
}
}
Error Responses
400 Bad Request
{
"error": "Query parameter is required",
"code": "MISSING_QUERY"
}
401 Unauthorized
{
"error": "Invalid API key",
"code": "INVALID_API_KEY"
}
402 Payment Required
{
"error": "Insufficient credits. Please upgrade your plan.",
"code": "INSUFFICIENT_CREDITS",
"details": {
"currentCredits": 0,
"requiredCredits": 1
}
}
429 Rate Limit Exceeded
{
"error": "Rate limit exceeded. Try again in 60 seconds.",
"code": "RATE_LIMIT_EXCEEDED",
"details": {
"retryAfter": 60,
"limit": 100,
"window": "1 minute"
}
}
Best Practices
Query Writing
- Be specific: “Find products under $100” vs “Find cheap products”
- Include context: Specify units, formats, and expected data types
- Use examples: “Show top 5 products by sales” is clearer than “Show best products”
- Use schemas: Structured responses are processed faster
- Limit results: Specify exact counts (“top 10”) rather than unbounded queries
- Cache responses: Store frequently used query results locally
- Batch queries: Combine related questions into single requests
Security
- Environment variables: Store API keys securely
- Server-side only: Never expose API keys in client-side code
- Validate inputs: Sanitize user-provided queries and data
- Monitor usage: Track API calls and token consumption
