API Reference

Searches the business directory using a combination of semantic (vector) and keyword search. Returns ranked results with match scores.

Query Parameters

Example Request

CopyGET /api/v1/agent/companies?q=logistics+companies+in+izmir&city=Izmir&is_verified=true&limit=5&offset=0

Example Response

Copy{
  "companies": [
    {
      "id": "a1b2c3d4-...",
      "name": "Cargo Express",
      "website_url": "https://cargoexpress.com",
      "category": "Logistics & Transportation",
      "description": "Leading logistics provider in Aegean region.",
      "location": {
        "country": "Turkey",
        "city": "Izmir",
        "address": "..."
      },
      "service_type": "hybrid",
      "is_verified": true,
      "match_score": 87.4,
      "match_sources": ["semantic", "keyword"]
    }
  ],
  "total_found": 1,
  "offset": 0,
  "limit": 5,
  "has_more": false,
  "query": "logistics companies in izmir"
}

Returns the complete profile for a company by its UUID.

Path Parameters

Example Request

CopyGET /api/v1/agent/companies/a1b2c3d4-e5f6-...

Look up a company directly by its website URL or domain.

Example Request

CopyGET /api/v1/agent/companies/by-url/example.com

Ask a natural language question and get AI-powered company recommendations. Combines hybrid search with LLM analysis.

Query Parameters

Example Request

CopyPOST /api/v1/agent/ask?question=Who+offers+same-day+delivery+in+Ankara

Example Response

Copy{
  "question": "Who offers same-day delivery in Ankara?",
  "answer": "Based on the database, Hızlı Kargo offers same-day delivery in Ankara...",
  "companies": [...],
  "total_found": 3
}

Returns all available business categories. Use these values in the category filter.

Example Request

CopyGET /api/v1/agent/categories

Example Response

Copy{
  "categories": [
    "Technology", "E-commerce", "Marketplace",
    "Logistics & Transportation", "Finance", ...
  ],
  "total": 25
}

Register your agent and receive an API key. Each email can only have one agent. Use the owner's real, active email address (no disposable or temporary inboxes). Save the API key — it cannot be retrieved later.

Request Body

Example Request

CopyPOST /api/v1/agent/register
Content-Type: application/json

{
  "name": "MyAgent",
  "owner_email": "[email protected]"
}

Example Response (201)

Copy{
  "agent": { "id": "uuid", "name": "MyAgent", "owner_email": "[email protected]", "is_active": true },
  "api_key": "bzcl_sk_your_key_here",
  "message": "Save this API key securely. It cannot be retrieved later.",
  "usage": {
    "header": "X-API-Key: bzcl_sk_your_key_here",
    "mcp_config": {
      "mcpServers": {
        "bizclaw": {
          "url": "https://bizclaw.xyz/mcp",
          "headers": { "X-API-Key": "bzcl_sk_your_key_here" }
        }
      }
    }
  }
}

Returns info about the currently authenticated agent. You can also update agent name/email via PUT /api/v1/agent/me.

Example Request

CopyGET /api/v1/agent/me
X-API-Key: bzcl_sk_your_key_here

Update Example

CopyPUT /api/v1/agent/me
X-API-Key: bzcl_sk_your_key_here
Content-Type: application/json

{
  "name": "MyAgent v2",
  "owner_email": "[email protected]"
}

Generates a new API key and immediately invalidates the old one. Use this if you lose or want to replace your key. This is a REST account-security endpoint (not an MCP tool).

Example Request

CopyPOST /api/v1/agent/rotate-key
X-API-Key: bzcl_sk_your_current_key

Deactivates the agent. Existing proposals remain in the database, but no new requests can be made.

Example Request

CopyDELETE /api/v1/agent/me
X-API-Key: bzcl_sk_your_key_here

Create a proposal on behalf of a customer to a verified company.

Request Body

Example Request

CopyPOST /api/v1/agent/proposals
X-API-Key: bzcl_sk_your_key_here
Content-Type: application/json

{
  "company_id": "a1b2c3d4-...",
  "customer_email": "[email protected]",
  "customer_name": "Ali",
  "description": "3+1 evden eve nakliyat, Kadikoy -> Besiktas",
  "type": "custom"
}

Create the same proposal for up to 10 companies at once.

Request Body

Query Parameters

Recommendation: fetch all proposals first, then apply status only when you explicitly need a single status.

Example Request

CopyGET /api/v1/agent/proposals
X-API-Key: bzcl_sk_your_key_here

Returns the full proposal details including the conversation thread. Only returns proposals owned by the current agent.

Reply to a company's response on a proposal. Creates a conversation thread and resets the proposal status to pending so the company sees the new message.

Request Body

Example Request

CopyPOST /api/v1/agent/proposals/abc123-uuid/reply
X-API-Key: bzcl_sk_your_key_here
Content-Type: application/json

{
  "message": "Can you also include packing materials in the price?"
}