API Reference

Everything you need to integrate URLmind into your product.

Introduction

URLmind is an async research API. You submit a business URL, we crawl it, extract structured data with AI, and return a rich company profile. The typical flow is: start → poll → use.

All responses follow a consistent envelope:

Response envelope

{
  "success": true,
  "data": { /* payload */ }
}

// On error:
{
  "success": false,
  "error": "Human-readable error message"
}

Authentication

All API requests require your API key in the Authorization header. You can find your key in the Dashboard → Settings.

Request header

Authorization: Bearer rk_your_api_key_here

Keep your key secret. Never expose it client-side or commit it to version control. Use environment variables.

Base URL

Production

https://urlmind.com/api/v1

Errors

HTTP Status	Meaning
400	Bad request — missing or invalid parameters
401	Unauthorized — missing or invalid API key
402	Payment required — no credits remaining
404	Not found — resource doesn't exist
429	Rate limited — slow down requests
500	Server error — retry with exponential backoff

Research

POST /research Start a new research job

Submits a URL for research. Returns a job_id immediately — use it to poll for results. Consumes 1 credit.

Request body

Field	Type	Description
url	string	required — The business website URL to research

Request

curl -X POST https://urlmind.com/api/v1/research \
  -H "Authorization: Bearer rk_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Response

{
  "success": true,
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending"
  }
}

GET /research/:job_id Poll job status

Returns the current status of a research job. Poll every 3–5 seconds until status is complete or failed.

Request

curl https://urlmind.com/api/v1/research/550e8400-... \
  -H "Authorization: Bearer rk_..."

Response — in progress

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "crawling",
    "company_id": null
  }
}

Response — complete

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "complete",
    "company_id": "7f3d9c2a-...",
    "processing_time_ms": 18450
  }
}

Companies

GET /companies/:company_id Get company profile

Returns the full structured company profile. Use the company_id from a completed research job.

Request

curl https://urlmind.com/api/v1/companies/7f3d9c2a-... \
  -H "Authorization: Bearer rk_..."

Response

{
  "success": true,
  "data": {
    "id": "7f3d9c2a-...",
    "name": "Acme Corp",
    "website_url": "https://acme.com",
    "description": "AI-powered widget manufacturer...",
    "industry": ["Manufacturing", "SaaS"],
    "contact": {
      "phone": "+1 (555) 123-4567",
      "email": "hello@acme.com",
      "address": { "city": "San Francisco", "state": "CA" }
    },
    "services": [{ "name": "Enterprise Plan", "description": "..." }],
    "hours": { "monday": { "open": "09:00", "close": "18:00" } },
    "metadata": {
      "confidence_scores": {
        "overall": 0.87,
        "contact": 0.95,
        "services": 0.82,
        "hours": 0.78
      }
    }
  }
}

Export

GET /export Download a formatted export

Returns the company profile in the requested format as a file download.

Query parameters

Parameter	Type	Description
company_id	string	required — Company UUID
format	string	required — One of `claude_md`, `json`, `mcp_config`

Examples

# CLAUDE.md — paste into any AI tool
curl "https://urlmind.com/api/v1/export?company_id=7f3d9c2a-...&format=claude_md" \
  -H "Authorization: Bearer rk_..." \
  -o company.md

# JSON — structured data for your app
curl "https://urlmind.com/api/v1/export?company_id=7f3d9c2a-...&format=json" \
  -H "Authorization: Bearer rk_..." \
  -o company.json

# MCP Config — connect to Claude Desktop
curl "https://urlmind.com/api/v1/export?company_id=7f3d9c2a-...&format=mcp_config" \
  -H "Authorization: Bearer rk_..." \
  -o mcp.json

Job statuses

Status	Meaning
pending	Job queued, not yet started
crawling	Fetching the website and subpages
extracting	AI extraction in progress
enriching	Cross-referencing data sources
complete	Profile ready — `company_id` available
failed	Research failed — credit not consumed

Company schema

Key fields returned in the company profile:

Field	Type	Description
id	uuid	Unique company identifier
name	string	Business name
website_url	string	Primary website URL
description	string	AI-generated business summary
industry	string[]	Industry categories
contact	object	Phone, email, address, social links
hours	object	Business hours by day of week
services	object[]	Products/services with descriptions and pricing
brand_voice	object	Tone, key messages, tagline, USPs
reviews_summary	object	Ratings aggregated from Google, Yelp, etc.
team	object[]	Team members with roles
metadata.confidence_scores	object	0–1 confidence per field (overall, contact, services, hours, brand, reviews)
metadata.gaps	string[]	Fields with missing or low-confidence data

Rate limits

Plan	Credits / month	Requests / minute
Explorer (free)	3	10
Build	20	30
Scale	75	60
Agency	250	120

When rate limited, you'll receive a 429 response. Implement exponential backoff starting at 1 second.