Complete reference for the Connectively Free API
https://connectively.us/api/external-usersJWT Token in x-access-token header
v1.0.0
The Connectively Free API allows you to authenticate and discover available questions for free users.
Copy this prompt into your AI coding agent (Claude Code, Cursor, Copilot, etc.) to scaffold a typed API client for these endpoints.
Implement a typed API client for the Connectively Free API.
Base URL: https://connectively.us/api/external-users
Reference docs: https://connectively.us/api-integration/documentation/free
## Authentication
- Every endpoint except POST /login requires a JWT.
- Obtain a token via POST /login with a JSON body { "username": ..., "password": ... }. The token is returned in the `x-access-token` RESPONSE header, not the response body.
- Send that token in the `x-access-token` REQUEST header on all authenticated calls.
- Tokens expire after 24 hours — re-authenticate when a request returns 401.
## Endpoints
### Authentication
- POST /login — Authenticate free user
Request body (application/json): { username: string (required), password: string (required, 8-30 chars) }
Returns: JWT token in x-access-token header
### Questions
- GET /question-list — Get question list
Query params: top_opportunities (string, optional) — If set to "true", returns top opportunities instead of regular feed questions
Returns: array with question, source, due_date, publicLink, featuredQuestionId, sourceUrl, isHaroQuery, categories, agenticScore
## Error handling
Handle these status codes:
- 400: validation error — surface the message
- 401: token missing/expired — re-authenticate and retry once
- 403: insufficient permissions
## Requirements
- Use my project's language and HTTP conventions (default to TypeScript with fetch if unspecified).
- Expose one typed method per endpoint, with typed request and response models matching the fields above.
- Read credentials from environment variables; never hard-code them.
- Centralize auth: obtain and cache the token, attach the `x-access-token` header automatically, and transparently re-login on a 401.
- Add a small usage example showing login followed by one authenticated call.All endpoints (except /login) require authentication via JWT token
Authenticate using the /login endpoint with your username and password. The token is returned in the x-access-token response header.
Include the token in the x-access-token header for all authenticated requests:
x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Tokens are valid for 24 hours. It's recommended to call the login endpoint for each request.
/loginAuthenticate a free user with username and password, returning a JWT token
Content-Type: application/json
{
"username": "string (required)",
"password": "string (required, 8-30 chars)"
}Response Body:
{
"responseHeaders": {
"x-access-token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImpvaG4uZG9lIiwicm9sZSI6ImV4dGVybmFsIn0.example"
}
}/question-listRetrieve a list of active questions available for free users. Questions are sorted by due date (earliest first).
x-access-token(string, required)JWT token for API authentication. Obtain this token from the /login endpoint.
x-access-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImpvaG4uZG9lIiwicm9sZSI6ImV4dGVybmFsIn0.exampletop_opportunities(string, optional)If set to "true", returns top opportunities instead of regular feed questions
Response Body:
[
{
"question": "What are the latest trends in AI?",
"source": "TechCrunch",
"due_date": "2024-01-30T23:59:59Z",
"publicLink": "https://connectively.us/public-link/source/question-slug",
"featuredQuestionId": 12345,
"sourceUrl": "https://techcrunch.com/article",
"isHaroQuery": true,
"categories": [
"Technology",
"AI"
],
"agenticScore": 64
}
]Endpoints return JSON objects or arrays with the requested data.
Errors are typically returned as plain text or JSON with error details:
For API support, please contact:
Email: support@connectively.us