API Reference
All endpoints require a Bearer token. Hosted clients should use OAuth 2.1 with PKCE. Local clients can use manual tokens minted via /api/tokens. The REST endpoints at /api/v1/* mirror the MCP tools - same schemas, same auth.
DISCOVERY
GET /.well-known/oauth-authorization-server
RFC 8414 OAuth authorization server metadata. Hosted MCP clients should fetch this first. No auth required.
curl exampleCURL
curl https://hubblefield.ai/.well-known/oauth-authorization-server
sample responseJSON
{
"issuer": "https://hubblefield.ai",
"authorization_endpoint": "https://hubblefield.ai/api/oauth/authorize",
"token_endpoint": "https://hubblefield.ai/api/oauth/token",
"registration_endpoint": "https://hubblefield.ai/api/oauth/register",
"revocation_endpoint": "https://hubblefield.ai/api/oauth/revoke",
"scopes_supported": ["read", "write_listing"],
"response_types_supported": ["code"],
"grant_types_supported": ["authorization_code"],
"code_challenge_methods_supported": ["S256"]
}REGISTER
POST /api/oauth/register
Dynamic client registration (RFC 7591). Call this if your client does not auto-register. Returns a client_id to use in the authorize step.
curl exampleCURL
curl -X POST https://hubblefield.ai/api/oauth/register -H "Content-Type: application/json" -d '{
"client_name": "My MCP Agent",
"redirect_uris": ["https://myagent.example.com/callback"],
"grant_types": ["authorization_code"],
"response_types": ["code"],
"token_endpoint_auth_method": "none"
}'sample responseJSON
{
"client_id": "hf_client_••••••••",
"client_name": "My MCP Agent",
"redirect_uris": ["https://myagent.example.com/callback"],
"grant_types": ["authorization_code"],
"response_types": ["code"],
"token_endpoint_auth_method": "none"
}AUTHORIZE
GET /api/oauth/authorize
Standard auth code + PKCE flow. Redirect the user here. On approval, HubbleField redirects to your redirect_uri with a code parameter.
query parameters
client_id required Your registered client_id
redirect_uri required Must match registration
response_type required "code"
scope required "read" or "write_listing"
code_challenge required Base64url(SHA-256(code_verifier))
code_challenge_method required "S256"
state optional Opaque value for CSRF protection
TOKEN EXCHANGE
POST /api/oauth/token
Exchange the auth code for a Bearer token. Include the code_verifier matching the challenge from the authorize step.
curl exampleCURL
curl -X POST https://hubblefield.ai/api/oauth/token -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=authorization_code" -d "code=CODE_FROM_REDIRECT" -d "client_id=hf_client_••••••••" -d "redirect_uri=https://myagent.example.com/callback" -d "code_verifier=YOUR_CODE_VERIFIER"
sample responseJSON
{
"access_token": "hf_live_••••••••",
"token_type": "Bearer",
"expires_in": 2592000,
"scope": "read"
}MINT TOKEN
POST /api/tokens
Session-backed alternative to OAuth. Sign in via the web UI first, then call this endpoint to mint a long-lived token for local stdio clients. Not suitable for hosted agents - use OAuth instead.
curl exampleCURL
curl -X POST https://hubblefield.ai/api/tokens -H "Content-Type: application/json" -H "Cookie: sparkraise_session=SESSION_COOKIE" -d '{ "label": "claude-desktop-local", "scope": "read" }'Note: magic-link sign-in is not available as a REST endpoint by design. An agent cannot fully automate human signup via REST (anti-abuse). The human must sign in via the web UI before a session-backed token can be minted.
SEARCH COMPANIES
POST /api/v1/search_companies
Full-text and filter search across published listings. Same schema as the MCP search_companies tool.
curl exampleCURL
curl -X POST https://hubblefield.ai/api/v1/search_companies -H "Authorization: Bearer hf_live_••••••••" -H "Content-Type: application/json" -d '{
"q": "fintech",
"sectors": ["FinTech"],
"raising_now": true,
"limit": 10
}'sample responseJSON
{
"results": [
{
"slug": "nimbus-ai",
"name": "Nimbus AI",
"one_liner": "Observability for LLM pipelines",
"sector": ["DevTools", "AI"],
"stage": "seed",
"raising_now": true
}
],
"count": 1,
"_disclaimer": "Information only. Not investment advice."
}GET COMPANY
GET /api/v1/get_company/[slug]
Retrieve a single company profile by slug. Returns public-tier fields only. 404 if not found or not published.
curl exampleCURL
curl https://hubblefield.ai/api/v1/get_company/nimbus-ai -H "Authorization: Bearer hf_live_••••••••"
sample responseJSON
{
"company": {
"slug": "nimbus-ai",
"name": "Nimbus AI",
"one_liner": "Observability for LLM pipelines",
"sector": ["DevTools", "AI"],
"stage": "seed",
"hq_country": "GB",
"website": "https://nimbus.ai",
"raising_now": true
},
"_disclaimer": "Information only. Not investment advice."
}REVOKE
POST /api/oauth/revoke
Revoke an OAuth access token (RFC 7009). Also available at POST /api/tokens/revoke for session-minted tokens.
curl exampleCURL
curl -X POST https://hubblefield.ai/api/oauth/revoke -H "Content-Type: application/x-www-form-urlencoded" -d "token=hf_live_••••••••"