Developer documentation

Machine-readable resources

• OpenAPI spec: https://saleshog.co/openapi.json
• Agent instructions (llms.txt): https://saleshog.co/llms.txt
• Authorization server metadata: https://saleshog.co/.well-known/oauth-authorization-server
• Protected resource metadata: https://saleshog.co/.well-known/oauth-protected-resource

Authentication

MCP clients connect with OAuth 2.1 and PKCE. SalesHog supports public clients only. The client registers, sends the user through authorization, and receives an access token as part of that flow. There is no manual token setup inside the dashboard.

In practice, the flow is:

1. Discover the OAuth metadata endpoints.
2. Register a public client.
3. Redirect the user to approve access.
4. Exchange the authorization code for a short-lived bearer token.
5. Use that token from the external client when calling the MCP endpoint.

End users do not need to generate tokens by hand. If they are connecting Claude, Cursor, or another MCP client, that client handles the token exchange.

MCP server

The MCP endpoint is https://saleshog.co/mcp. It speaks JSON-RPC 2.0 over HTTP and is intended for connected clients rather than manual use.

Available tools include business info, signals, mentions, metrics, weekly reports, outreach drafting, usage checks, and more. Outreach always requires explicit user approval before anything is sent.

Errors

API errors return structured JSON with a machine-readable code and a short hint. Common codes include bad_request, unauthorized, forbidden, not_found, method_not_allowed, conflict, rate_limited, and server_error.

Rate limits

Rate-limited endpoints return standard headers so clients can back off cleanly:

• RateLimit-Limit: requests allowed in the current window.
• RateLimit-Remaining: requests left in the current window.
• RateLimit-Reset: seconds until reset.
• Retry-After: wait time returned with HTTP 429.