Base URL and Versioning

All Prospector API endpoints are served under the GhostStack API base URL with a versioned path prefix:

https://api.ghoststack.dev/v1/prospector

The current stable version is v1. Breaking changes are introduced in new major versions only. Minor additions (new fields, new endpoints) are added to the current version without bumping the major number.

Authentication

API requests require a Bearer token in the Authorization header. Generate an API token in the GhostStack dashboard under Settings > API Tokens. Tokens are scoped to specific tools, so make sure your token includes the prospector scope.

curl -H "Authorization: Bearer gsk_your_token_here" \
  https://api.ghoststack.dev/v1/prospector/leads

Tokens do not expire by default, but you can set an expiration date when creating them. Revoked tokens return a 401 Unauthorized response immediately.

Core Endpoints

Leads

Method	Path	Description
GET	/leads	List scored leads with optional filters
GET	/leads/:id	Get a single lead with full score breakdown
POST	/leads/scan	Trigger an on-demand scan
PATCH	/leads/:id	Update lead status or tags

# List leads scored above 70, sorted by score descending
curl -H "Authorization: Bearer gsk_..." \
  "https://api.ghoststack.dev/v1/prospector/leads?min_score=70&sort=-score"

Proposals

Method	Path	Description
GET	/proposals	List proposals with status filter
GET	/proposals/:id	Get proposal details including draft text
POST	/proposals	Generate a proposal for a lead
PATCH	/proposals/:id	Update proposal text or status
POST	/proposals/:id/submit	Submit a proposal to the platform

Contracts

Method	Path	Description
GET	/contracts	List active and completed contracts
GET	/contracts/:id	Get contract details with milestones
PATCH	/contracts/:id/milestones/:mid	Update milestone status

Scoring

Method	Path	Description
GET	/scoring/config	Get current scoring weights and parameters
PUT	/scoring/config	Update scoring configuration
POST	/scoring/backtest	Run a backtest with proposed config

Request and Response Format

All endpoints accept and return JSON. Request bodies should use Content-Type: application/json. Responses include a top-level data key for the resource and a meta key for pagination info where applicable.

{
  "data": [
    {
      "id": "lead_3f8k2m",
      "job_title": "React Native App Development",
      "platform": "upwork",
      "score": {
        "composite": 82,
        "confidence": 0.87,
        "signals": {
          "skill_match": 90,
          "budget": 75,
          "client_history": 88,
          "competition": 70,
          "timeline": 80
        }
      },
      "status": "new",
      "created_at": "2026-04-20T14:30:00Z"
    }
  ],
  "meta": {
    "total": 47,
    "page": 1,
    "per_page": 20
  }
}

Pagination

List endpoints return paginated results. Use page and per_page query parameters to navigate. The maximum per_page value is 100. The meta object in the response includes total, page, and per_page fields.

# Page 2, 50 results per page
curl -H "Authorization: Bearer gsk_..." \
  "https://api.ghoststack.dev/v1/prospector/leads?page=2&per_page=50"

Rate Limits

API requests are rate-limited per token:

Plan	Requests per minute	Requests per day
Starter	60	5,000
Pro	120	25,000
Team	300	100,000

Rate limit headers are included in every response:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1714000000

When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

Error Responses

Errors follow a consistent format:

{
  "error": {
    "code": "validation_error",
    "message": "min_score must be between 0 and 100",
    "details": {
      "field": "min_score",
      "value": 150
    }
  }
}

Common error codes: authentication_error (401), forbidden (403), not_found (404), validation_error (422), rate_limited (429), internal_error (500).