Skip to main content
POST
/
v1
/
search
/
jobs
Create Search Job
curl --request POST \
  --url https://api.stru.ai/v1/search/jobs \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '{
  "query": "<string>",
  "design_standard": "<string>",
  "document_id": "<string>",
  "page": 123,
  "per_page": 123
}'
{
  "400": {},
  "401": {},
  "429": {},
  "job_id": "<string>",
  "status": "<string>",
  "created_at": "<string>"
}

​
Overview

Create an asynchronous search job to find relevant clauses, requirements, and specifications across the building code library. The API immediately returns a job ID for tracking the search progress.
Asynchronous Operation: This endpoint returns immediately with a job ID. Use the Get Job Status endpoint to poll for results.

​
Authentication

​
Authorization
string
required
Bearer token (API key from app.stru.ai)
Authorization: Bearer sk_live_abc123...

​
Request Body

​
query
string
required
Search query string (1-500 characters)Supports multiple query types:
  • Section numbers: "Section 10.5.3"
  • Code references: "AISC 360-16 G2.1"
  • Technical terms: "reinforcement requirements"
  • Natural language: "What are deflection limits for steel beams?"
"query": "load combinations for seismic design"
​
design_standard
string
Filter by regional design standard (optional)Valid values:
  • "us" - US standards (AISC, ACI, ASCE)
  • "eurocode" - European codes (EN 1992)
  • "aus-nz" - Australian/NZ (AS codes)
  • "canada" - Canadian codes (CSA)
"design_standard": "us"
​
document_id
string
Search within a specific document only (optional)
"document_id": "asce-7-22"
​
page
number
default:"1"
Page number for pagination (≥ 1)
"page": 1
​
per_page
number
default:"25"
Results per page (1-100)
"per_page": 25

​
Response

Returns a job object with status “pending” or “in_progress”.
​
job_id
string
Unique job identifier for tracking
"job_abc123xyz"
​
status
string
Current job status: "pending" or "in_progress"
"pending"
​
created_at
string
ISO 8601 timestamp when job was created
"2025-10-17T10:30:00Z"

​
Example Requests

curl -X POST https://api.stru.ai/v1/search/jobs \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "deflection limits for steel beams"
  }'

​
Example Response

{
  "job_id": "job_abc123xyz",
  "status": "pending",
  "created_at": "2025-10-17T10:30:00Z"
}
Status Code: 202 Accepted - Job created and queued for processing

​
Error Responses

​
400
Bad Request
Invalid request parameters
{
  "error": {
    "code": "INVALID_QUERY",
    "message": "Query string is required and must be 1-500 characters"
  }
}
​
401
Unauthorized
Missing or invalid API key
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}
​
429
Rate Limit Exceeded
Too many requests
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit of 120 requests/minute exceeded",
    "retry_after": 45
  }
}

​
Query Types & Examples

Search for specific code sections.Examples:
  • "Section 10.5.3"
  • "Chapter 9 reinforcement"
  • "AISC 360-16 G2.1"
  • "Table 4.3-1"
Best for: Finding exact code references
Search using engineering terminology.Examples:
  • "reinforcement requirements"
  • "load combinations"
  • "shear strength calculation"
  • "moment frame design"
Best for: Finding relevant clauses on a topic
Ask questions in plain English.Examples:
  • "What are the deflection limits for steel roof beams?"
  • "How do I calculate seismic base shear?"
  • "What are the reinforcement spacing requirements?"
Best for: Exploratory research and learning
Search for tables and diagrams.Examples:
  • "load factor table"
  • "Figure 6.2 connection details"
  • "Table of material properties"
Best for: Finding reference tables and diagrams

​
Best Practices

Be specific - More specific queries yield better results. Instead of “steel”, use “steel beam deflection limits”
Filter when possible - Use design_standard or document_id to reduce noise and improve relevance
Start with semantic search - Let the AI understand your intent, then refine with section numbers if needed
Use pagination - For broad queries, use per_page to control result count and reduce response size
Hybrid approach: Try a natural language query first, then if you find a relevant section, search for that specific section number to find related clauses.
Rate limits: Stay within 120 requests/minute. Implement exponential backoff when polling for results to avoid rate limit errors.

​
Next Steps

After creating a search job:
1

Poll for Completion

Use Get Job Status to check if the search is complete
GET /v1/jobs/{job_id}
2

Retrieve Results

When status is "completed", the response includes the full search results
{
  "status": "completed",
  "results": {
    "total": 15,
    "matches": [...]
  }
}
3

Process Matches

Use the page numbers, snippets, and context to integrate results into your application