Skip to main content

​
Endpoint

POST /api/start-job

​
Description

Initiates a new service job request. This endpoint:
  1. Calls Grok LLM to infer the task type from the user’s query
  2. Generates up to 5 clarifying questions specific to the task
  3. Creates a Job object stored in-memory
  4. Returns a job_id, inferred task, and questions for the user to answer

​
Request Body

​
query
string
required
User’s free text query describing the service needed.Example: "fix my toilet"
​
house_address
string
required
Full house address where the service is needed.Example: "123 Main St, San Jose, CA 95126"
​
zip_code
string
required
ZIP code for the service location. Used for provider search.Example: "95126"
​
price_limit
number | string
required
Maximum price the user is willing to pay. Can be a dollar amount or the string "no_limit".Example: 250 or "no_limit"
​
date_needed
string
required
Date when the service is needed in ISO format.Example: "2025-12-10"

​
Response

​
job_id
string
Unique identifier for the created job. Use this ID in subsequent API calls.Example: "550e8400-e29b-41d4-a716-446655440000"
​
task
string
The inferred task type determined by Grok LLM from the user’s query.Example: "plumber"
​
questions
array
Array of clarifying questions (up to 5) to gather more context about the job.

​
Example Request

curl -X POST http://localhost:8000/api/start-job \
  -H "Content-Type: application/json" \
  -d '{
    "query": "fix my toilet",
    "house_address": "123 Main St, San Jose, CA 95126",
    "zip_code": "95126",
    "price_limit": 250,
    "date_needed": "2025-12-10"
  }'

​
Example Response

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "task": "plumber",
  "questions": [
    {
      "id": "q1",
      "question": "What is the specific issue with your toilet?"
    },
    {
      "id": "q2",
      "question": "Is the toilet running constantly or leaking?"
    },
    {
      "id": "q3",
      "question": "How old is your toilet?"
    },
    {
      "id": "q4",
      "question": "Have you noticed any water damage?"
    },
    {
      "id": "q5",
      "question": "Is this an emergency?"
    }
  ]
}

​
Error Responses

{
  "detail": "Error starting job: Connection to Grok LLM failed"
}

​
Next Steps

After receiving the job_id and questions:
  1. Present the questions to the user
  2. Collect their answers
  3. Call POST /api/complete-job with the job_id and answers to find service providers

​
Implementation Details

Job Storage: Jobs are stored in-memory and do not persist to the database. The job object contains:
  • Original query and inferred task
  • User location (address, ZIP code)
  • Constraints (price limit, date needed)
  • Clarifying questions and answers (once provided)
  • Job status (starts as "collecting_info")
Task Inference: Uses Grok LLM to analyze the user’s natural language query and determine the service category (e.g., “plumber”, “electrician”, “handyman”). Question Generation: Uses Grok LLM to generate contextual questions based on the task type, user query, location, and constraints.

Build docs developers (and LLMs) love

Get started for freeTalk to us