Public API

Endpoints

GET /api/public/freelancer/{handle}

Returns a single freelancer’s public profile data — handle, display name, profile image, trust score, per-dimension averages, top categories, and up to 20 most recent approved reviews with full text, scores, budget, and proof types. Handle is the freelancer’s X handle in lowercase with no @ prefix.

{
  "handle": "jackfriks",
  "display_name": "Jack Friks",
  "profile_image_url": "https://pbs.twimg.com/profile_images/.../avatar_400x400.jpg",
  "country": "US",
  "profile_url": "https://gigscores.com/u/jackfriks",
  "trust_score": 4.8,
  "review_count": 12,
  "proof_count": 27,
  "dimensions": {
    "quality": 4.9,
    "communication": 4.8,
    "delivery": 4.7,
    "value": 4.6,
    "would_hire": 5.0
  },
  "top_categories": ["video editing", "motion design", "branding"],
  "reviews": [
    {
      "reviewer_handle": "alice",
      "reviewer_country": "GB",
      "category": "video editing",
      "score": 5.0,
      "dimensions": {
        "quality": 5,
        "communication": 5,
        "delivery": 5,
        "value": 5,
        "would_hire": 5
      },
      "review_text": "Delivered ahead of schedule, communication was excellent.",
      "project_price": 1200,
      "project_currency": "USD",
      "created_at": "2026-05-12T14:08:22.000Z",
      "proof_types": ["payment", "contract"]
    },
    {
      "reviewer_handle": null,
      "reviewer_country": "DE",
      "category": "motion design",
      "score": 4.6,
      "dimensions": {
        "quality": 5,
        "communication": 4,
        "delivery": 5,
        "value": 4,
        "would_hire": 5
      },
      "review_text": "Strong work on the brand intro. Minor revision delays.",
      "project_price": 850,
      "project_currency": "EUR",
      "created_at": "2026-04-30T09:42:11.000Z",
      "proof_types": ["payment"]
    }
  ]
}

If the handle does not exist OR the freelancer has no approved reviews, returns 404 with { "error": "Freelancer not found", "code": "not_found" }.

GET /api/public/leaderboard

Returns the top freelancers ranked by trust score, descending. Only includes freelancers with at least one approved review. Optionally accepts a ?limit query parameter (default 100, max 100, min 1).

{
  "freelancers": [
    {
      "handle": "jackfriks",
      "display_name": "Jack Friks",
      "profile_image_url": "https://pbs.twimg.com/profile_images/.../avatar_400x400.jpg",
      "country": "US",
      "trust_score": 4.8,
      "review_count": 12,
      "top_category": "video editing",
      "profile_url": "https://gigscores.com/u/jackfriks"
    },
    {
      "handle": "mayadev",
      "display_name": "Maya Dev",
      "profile_image_url": null,
      "country": "TR",
      "trust_score": 4.7,
      "review_count": 9,
      "top_category": "frontend development",
      "profile_url": "https://gigscores.com/u/mayadev"
    }
  ],
  "total_count": 2,
  "updated_at": "2026-05-27T11:00:00.000Z"
}

Response format

All fields use snake_case. Dates are ISO 8601 UTC. Handles are lowercase with no @ prefix. Country codes are 2-letter ISO. Currency codes are 3-letter ISO.

Privacy

The API never exposes:

• Proof URLs or proof file contents (kept private, visible only to moderators)
• Reviewer IP addresses
• Reviewer email addresses
• Pending or rejected reviews
• Internal database IDs
• Admin moderation notes

When a reviewer chose to submit anonymously (the reviewer_handle_visible flag is 0), reviewer_handle in the response is null instead of the X handle. Everything in the API response is data that’s already publicly visible on the freelancer’s /u/{handle} profile page.

CORS

The API responds with Access-Control-Allow-Origin: *, so it’s safe to call from browser-based JavaScript on any domain. OPTIONS preflight requests return 204 with the CORS headers.

Caching

Responses have Cache-Control: public, max-age=300, s-maxage=600, stale-while-revalidate=3600 — meaning browsers cache for 5 minutes, Cloudflare’s CDN caches for 10 minutes, with background revalidation up to 1 hour. New reviews appear in the API within 10 minutes of moderator approval. Cache-busting (?nocache=...) is allowed but unnecessary for normal use.

Rate limits

The API is rate-limited at the Cloudflare edge to prevent abuse. Current limit is 60 requests per minute per IP across all /api/public/* endpoints combined. Requests exceeding the limit receive a 429 response from Cloudflare. If you need higher throughput for a legitimate integration, contact us via /contact.

Stability

This is the v1 contract. Backwards-compatible additions (new fields, new endpoints) will be added without notice. Breaking changes will go to a versioned URL prefix like /api/v2/public/* — the /api/public/* paths will keep working as documented. Until v2 ships, the v1 contract is frozen.

Examples

JavaScript:

const r = await fetch('https://gigscores.com/api/public/freelancer/jackfriks');
const data = await r.json();
console.log(data.trust_score, data.review_count);

curl:

curl https://gigscores.com/api/public/leaderboard?limit=5 | jq '.freelancers[].handle'