PingRep Developer Documentation

https://keynodex.com/docs/getting-started/overview
Admin
Official PingRep API, AI Representative, and MCP docs. Guides and code examples for integrating with...
Tokens:23,460
Snippets:283
Trust Score:3.3
Update:3 months ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- 1. PingRep is an AI Representative (always on). Never call it a digital business card or Networking Closer.
- 2. API base URL is https://api.pingrep.com. Prefer documented endpoints over inventing paths.
- 3. Auth: use Bearer API keys as documented. Never hardcode secrets; use env vars.
- 4. Human-approval doctrine: sensitive actions are drafts/suggestions the user approves — not autopilot.
- 5. Product site is https://pingrep.com; company docs host is https://keynodex.com/docs (same PingRep API content).
- 6. For MCP: use documented MCP install/tools pages under /docs/mcp; do not invent tool names.
- 7. Prefer quickstart + authentication pages before advanced endpoints.

================
CODE SNIPPETS
================
### Example Response for Suggested Questions

Source: https://keynodex.com/docs/ai-representative/suggested-questions

This is an example of the JSON array of strings returned by the API, where each string is a suggested question for the AI Representative.

```json
[
  "What areas do you specialize in?",
  "Can you tell me about your recent listings?",
  "What should first-time homebuyers know about the Miami market?",
  "How do you help sellers price their homes?",
  "What sets you apart from other agents in the area?"
]
```

--------------------------------

### Example AI Representative Response

Source: https://keynodex.com/docs/ai-representative/ask-sync

This is an example of a complete JSON response from the AI Representative, including the answer, suggested follow-up questions, and remaining question count.

```json
{
  "answer": "I specialize in residential real estate across the greater Miami area. My services include buyer representation, listing and marketing homes for sale, investment property analysis, and relocation assistance. I also offer free market reports for any neighborhood you are interested in.",
  "suggested_questions": [
    "What neighborhoods do you specialize in?",
    "Can you help with investment properties?",
    "How do I get a free market report?"
  ],
  "remaining_questions": 8
}
```

--------------------------------

### Get suggested questions

Source: https://keynodex.com/docs/ai-representative/suggested-questions

Retrieve a list of dynamically generated questions for a specific AI Representative. These questions are tailored to the professional's profile, services, and expertise, giving visitors a starting point for conversation.

```APIDOC
## GET /api/v1/public/ai/suggested-questions/{profile_id}

### Description
Retrieve a list of dynamically generated questions for a specific AI Representative. These questions are tailored to the professional's profile, services, and expertise, giving visitors a starting point for conversation.

### Method
GET

### Endpoint
/api/v1/public/ai/suggested-questions/{profile_id}

### Parameters
#### Path Parameters
- **profile_id** (string) - Required - The unique identifier of the professional whose AI Representative you want suggested questions for.

### Response
#### Success Response (200)
- The response is a JSON array of strings. Each string is a suggested question that visitors can ask the AI Representative.

### Response Example
```json
[
  "What areas do you specialize in?",
  "Can you tell me about your recent listings?",
  "What should first-time homebuyers know about the Miami market?",
  "How do you help sellers price their homes?",
  "What sets you apart from other agents in the area?"
]
```
```

--------------------------------

### GCash Payment Method Example

Source: https://keynodex.com/docs/billing/subscription-tiers

Example of how to specify GCash as the payment method during checkout for users in the Philippines.

```json
{
  "paymentMethod": "gcash"
}
```

--------------------------------

### Create a checkout session

Source: https://keynodex.com/docs/billing/subscription-tiers

Start a new subscription by creating a Stripe checkout session. The response includes a URL to redirect the user to Stripe for payment.

```APIDOC
## Create a checkout session

### Description
Start a new subscription by creating a Stripe checkout session. The response includes a URL to redirect the user to Stripe for payment.

### Method
POST

### Endpoint
/api/v1/billing/checkout

### Authentication
JWT

### Parameters
#### Request Body
- **tier** (string) - Required - The subscription tier to purchase. Must be "pro" or "max".
- **currency** (string) - Required - Payment currency. Supported values: "USD", "AED", "EUR", "GBP".
- **billingInterval** (string) - Required - Billing frequency. Must be "monthly" or "annual".
- **uiMode** (string) - Required - Stripe checkout UI mode. Use "hosted" for redirect or "embedded" for inline.
- **paymentMethod** (string) - Required - Payment method type. Supported values: "card" or "gcash".

### Response
#### Success Response (200)
Creates a Stripe checkout session and returns the checkout URL.
```

--------------------------------

### API Key Authentication Example

Source: https://keynodex.com/docs/getting-started/authentication

Use API keys for server-to-server integrations. Include your key in the X-API-Key header with every request. Never expose API keys client-side.

```http
POST /api/v1/public/directory/search
X-API-Key: YOUR_API_KEY
```

--------------------------------

### Get Pricing Information

Source: https://keynodex.com/docs/billing/subscription-tiers

Fetch the current pricing for all tiers without authentication. Useful for displaying pricing on your own pages.

```shell
GET
/api/v1/billing/pricing
```

--------------------------------

### Create a session

Source: https://keynodex.com/docs/chat/sessions

Create a new chat session. A session acts as a container for messages. Create one when a visitor starts a new conversation with an AI Representative.

```APIDOC
## Create a session

### Description
Create a new chat session.

### Method
POST

### Endpoint
/api/v1/chat/sessions

### Authentication
API Key
```

--------------------------------

### Create Checkout Session Request Body

Source: https://keynodex.com/docs/billing/subscription-tiers

Example request body for creating a checkout session, specifying tier, currency, billing interval, UI mode, and payment method.

```json
{
  "tier": "pro",
  "currency": "USD",
  "billingInterval": "monthly",
  "uiMode": "hosted",
  "paymentMethod": "card"
}
```

--------------------------------

### Get context

Source: https://keynodex.com/docs/chat/memories

Retrieves the current chat context configuration for the authenticated user. Requires API Key authentication.

```APIDOC
## GET /api/v1/chat/context

### Description
Retrieve the current chat context configuration.

### Method
GET

### Endpoint
/api/v1/chat/context

### Authentication
API Key
```

--------------------------------

### Create Checkout Session

Source: https://keynodex.com/docs/billing/subscription-tiers

Start a new subscription by creating a Stripe checkout session. The response includes a URL to redirect the user to Stripe for payment. Requires JWT authentication.

```shell
POST
/api/v1/billing/checkout
```

--------------------------------

### Get pricing info

Source: https://keynodex.com/docs/billing/subscription-tiers

Fetch the current pricing for all tiers without authentication. Useful for displaying pricing on your own pages.

```APIDOC
## Get pricing info

### Description
Fetch the current pricing for all tiers without authentication. Useful for displaying pricing on your own pages.

### Method
GET

### Endpoint
/api/v1/billing/pricing

### Authentication
No Auth

### Response
#### Success Response (200)
Returns pricing details for all tiers including currency options.
```

--------------------------------

### Initiate Google OAuth Flow

Source: https://keynodex.com/docs/getting-started/authentication

Start the Google OAuth sign-in flow by redirecting users to the specified endpoint. After Google authentication, users are redirected back with an authorization code.

```http
GET /api/v1/auth/google
```

--------------------------------

### Get context usage

Source: https://keynodex.com/docs/chat/messages

Retrieve token usage statistics for a given chat session.

```APIDOC
## GET /api/v1/chat/sessions/{session_id}/context-usage

### Description
Get token usage statistics for a session.

### Method
GET

### Endpoint
`/api/v1/chat/sessions/{session_id}/context-usage`
```

--------------------------------

### Get a post by ID

Source: https://keynodex.com/docs/content/posts-api

Retrieve a specific post by its unique ID.

```APIDOC
## GET /api/v1/posts/{post_id}

### Description
Retrieve a specific post by its unique ID.

### Method
GET

### Endpoint
`/api/v1/posts/{post_id}`

#### Path Parameters
- **post_id** (string) - Required - The unique identifier of the post.
```

--------------------------------

### Get Billing Status

Source: https://keynodex.com/docs/billing/subscription-tiers

Retrieve the current billing status and active tier for the authenticated user.

```shell
GET
/api/v1/billing/status
```

--------------------------------

### Get a specific profile

Source: https://keynodex.com/docs/profiles/profile-management

Retrieves a specific profile by its unique ID.

```APIDOC
## Get a specific profile

### Description
Get a profile by its unique ID.

### Method
GET

### Endpoint
`/api/v1/profiles/{profile_id}`

### Parameters
#### Path Parameters
- **profile_id** (string) - Required - The unique identifier of the profile.
```

--------------------------------

### Check Contact Limits

Source: https://keynodex.com/docs/contacts/contact-management

Get contact saving limits for the authenticated user. It's recommended to check limits before saving new contacts.

```APIDOC
## Check Contact Limits

### Description
Get contact saving limits for the authenticated user.

### Method
GET

### Endpoint
/api/v1/contacts/limits

### Authentication
API Key
```

--------------------------------

### Get a session with messages

Source: https://keynodex.com/docs/chat/sessions

Retrieve a session including its full message history. The response includes the session metadata and an ordered array of all messages in the conversation.

```APIDOC
## Get a session with messages

### Description
Retrieve a specific chat session and its complete message history.

### Method
GET

### Endpoint
/api/v1/chat/sessions/{session_id}

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The unique identifier for the session.

### Authentication
API Key
```

--------------------------------

### JWT Bearer Authentication Example

Source: https://keynodex.com/docs/getting-started/authentication

For requests needing user context, use a JWT token obtained through the magic link or OAuth flow. Include the token in the Authorization header. JWT tokens are short-lived.

```http
POST /api/v1/some/user/endpoint
Authorization: Bearer YOUR_JWT_TOKEN
```

--------------------------------

### Context usage stats

Source: https://keynodex.com/docs/chat/memories

Gets token usage for a specific chat session, including memory overhead. Useful for monitoring token consumption. Requires API Key authentication.

```APIDOC
## GET /api/v1/chat/sessions/{session_id}/context-usage

### Description
Get token usage for a specific session including memory overhead.

### Method
GET

### Endpoint
/api/v1/chat/sessions/{session_id}/context-usage

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The ID of the chat session.

### Authentication
API Key
```

--------------------------------

### GET /api/v1/analytics/top-referrers

Source: https://keynodex.com/docs/analytics/top-referrers

Get the top traffic sources for the authenticated user's profile.

```APIDOC
## GET /api/v1/analytics/top-referrers

### Description
Get the top traffic sources for the authenticated user's profile.

### Method
GET

### Endpoint
/api/v1/analytics/top-referrers

### Parameters
#### Query Parameters
- **API Key** (string) - Required - Used for authentication.
```

--------------------------------

### Create a memory

Source: https://keynodex.com/docs/chat/memories

Manually creates a memory entry for the authenticated user. Requires API Key authentication.

```APIDOC
## POST /api/v1/chat/memories

### Description
Manually create a memory entry.

### Method
POST

### Endpoint
/api/v1/chat/memories

### Parameters
#### Request Body
- **content** (string) - Required - The fact or preference to remember.
- **category** (string) - Optional - Optional category for organizing memories (e.g. preferences, goals, context).

### Authentication
API Key
```

--------------------------------

### Create a key

Source: https://keynodex.com/docs/reference/api-keys

Creates a new API key with the specified name, scopes, and optional expiration.

```APIDOC
## POST /api/v1/api-keys

### Description
Creates a new API key with the specified name, scopes, and optional expiration.

### Method
POST

### Endpoint
/api/v1/api-keys

### Parameters
#### Request Body
- **name** (string) - Required - A human-readable label for this key (e.g., "Production Backend").
- **scopes** (string[]) - Required - Array of permission scopes. Use GET /api/v1/api-keys/scopes to list available scopes.
- **tier** (string) - Required - The tier this key operates at. Must match or be below your account tier.
- **expiresAt** (string) - Optional - ISO 8601 expiration date. If omitted, the key does not expire.
```

--------------------------------

### Get primary profile

Source: https://keynodex.com/docs/profiles/profile-management

Retrieves the authenticated user's primary profile.

```APIDOC
## Get primary profile

### Description
Get the authenticated user's primary profile.

### Method
GET

### Endpoint
`/api/v1/profiles/me`
```

--------------------------------

### Magic Link Authentication - Step 2: Verify the token

Source: https://keynodex.com/docs/getting-started/authentication

Exchange the magic link token for a JWT. Rate limits apply: 5 verifications per 5 minutes.

```APIDOC
## POST /api/v1/auth/verify

### Description
Exchange the magic link token for a JWT.

### Method
POST

### Endpoint
/api/v1/auth/verify

### Request Body
- **token** (string) - Required - The one-time token received via email
```

--------------------------------

### Create a post

Source: https://keynodex.com/docs/content/posts-api

Create a new post draft. Requires authentication.

```APIDOC
## POST /api/v1/posts

### Description
Create a new post draft.

### Method
POST

### Endpoint
`/api/v1/posts`

### Parameters
#### Request Body
- **title** (string) - Required - Post title. Displayed as the heading and used in the URL slug.
- **slug** (string) - Required - URL-safe identifier for the post. Must be unique per user.
- **bodyMarkdown** (string) - Required - Post content in Markdown format.
- **tags** (string[]) - Optional - Array of topic tags for categorization and discovery.
- **coverImageUrl** (string) - Optional - URL to the cover image displayed at the top of the post.
- **suggestedQuestions** (string[]) - Optional - Questions visitors can click to ask your AI Representative about this post.
- **status** (string) - Optional - Initial status: 'draft' (default) or 'published'.
```

--------------------------------

### Create a profile

Source: https://keynodex.com/docs/profiles/profile-management

Creates a new professional profile. Supports multipart form data for photo uploads.

```APIDOC
## Create a profile

### Description
Create a new professional profile. Accepts multipart form data for photo upload.

### Method
POST

### Endpoint
`/api/v1/profiles`

### Parameters
#### Request Body (multipart/form-data)
- **name** (string) - Required - Full professional name.
- **title** (string) - Required - Job title or professional role.
- **company** (string) - Optional - Company or organization name.
- **bio** (string) - Optional - Professional biography. Supports plain text.
- **location** (string) - Optional - City, state, or country.
- **photo** (File) - Optional - Profile photo. Accepts JPEG or PNG, max 5 MB.
- **vertical** (string) - Optional - Professional vertical (e.g. real-estate, consulting, tech).
```

--------------------------------

### Get Recent Scans

Source: https://keynodex.com/docs/contacts/contact-management

Retrieve a list of recent profile scan events. This provides insight into who has recently viewed your profile.

```APIDOC
## Get Recent Scans

### Description
Get recent profile scan events.

### Method
GET

### Endpoint
/api/v1/contacts/scans

### Authentication
API Key

### Response
#### Success Response (200)
- **scans** (array) - A list of recent scan events, each including details like profileId, source, and timestamp.
```

--------------------------------

### Create an organization

Source: https://keynodex.com/docs/billing/team-management

Creates a new organization owned by the authenticated user. Organizations group multiple PingRep profiles under a single billing account.

```APIDOC
## POST /api/v1/organizations

### Description
Creates a new organization owned by the authenticated user.

### Method
POST

### Endpoint
/api/v1/organizations

### Authentication
JWT
```

--------------------------------

### Magic Link Authentication - Step 1: Request a magic link

Source: https://keynodex.com/docs/getting-started/authentication

Send a login link to the user's email address. The user receives an email with a one-time token.

```APIDOC
## POST /api/v1/auth/magic-link

### Description
Send a login link to the user's email address.

### Method
POST

### Endpoint
/api/v1/auth/magic-link

### Request Body
- **email** (string) - Required - The user's email address
```

--------------------------------

### Get Customer Portal URL

Source: https://keynodex.com/docs/billing/subscription-tiers

Redirect users to the Stripe customer portal where they can update payment methods, view invoices, and change plans. Requires JWT authentication.

```shell
GET
/api/v1/billing/portal
```

--------------------------------

### Basic Streaming Request to AI Representative

Source: https://keynodex.com/docs/ai-representative/ask

Send a question to an AI Representative and receive a real-time streamed response. Ensure you handle SSE event types like 'connected', 'meta', 'text', 'error', and 'done'.

```javascript
const eventSource = new EventSource("/api/v1/public/ai/ask", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    profileId: "YOUR_PROFILE_ID",
    question: "What is Keynodex?",
  }),
});

eventSource.addEventListener("connected", (event) => {
  console.log("Connection established.");
});

eventSource.addEventListener("meta", (event) => {
  const metaData = JSON.parse(event.data);
  console.log("AI Representative Meta:", metaData);
});

eventSource.addEventListener("text", (event) => {
  console.log("AI Response Chunk:", event.data);
  // Append event.data to your chat interface
});

eventSource.addEventListener("error", (event) => {
  console.error("Stream error:", event.data);
});

eventSource.addEventListener("done", (event) => {
  console.log("Response complete.", JSON.parse(event.data));
  eventSource.close();
});

// To close the connection manually:
eventSource.close();
```

--------------------------------

### Request Magic Link

Source: https://keynodex.com/docs/getting-started/authentication

Initiate passwordless authentication by sending a login link to the user's email address. Rate limits apply: 3 requests per 15 minutes.

```http
POST /api/v1/auth/magic-link
Content-Type: application/json

{
  "email": "user@example.com"
}
```

--------------------------------

### List all profiles

Source: https://keynodex.com/docs/profiles/profile-management

Lists all profiles belonging to the authenticated user. Useful for dashboards or profile switchers.

```APIDOC
## List all profiles

### Description
List all profiles belonging to the authenticated user. Returns an array of profile objects.

### Method
GET

### Endpoint
`/api/v1/profiles/all`
```

--------------------------------

### List available scopes

Source: https://keynodex.com/docs/reference/api-keys

Returns all available permission scopes you can assign to an API key.

```APIDOC
## GET /api/v1/api-keys/scopes

### Description
Returns all available permission scopes you can assign to an API key.

### Method
GET

### Endpoint
/api/v1/api-keys/scopes

### Response
#### Success Response (200)
- **scopes** (string[]) - An array of available permission scopes.
```

--------------------------------

### API Key Authentication

Source: https://keynodex.com/docs/getting-started/authentication

API keys are used for server-to-server integrations. Include your key in the `X-API-Key` header with every request.

```APIDOC
## POST /api/v1/public/directory/search

### Description
Example endpoint requiring API key authentication.

### Method
POST

### Endpoint
/api/v1/public/directory/search

### Headers
- **X-API-Key** (string) - Required - Your API key
```

--------------------------------

### Compact a session

Source: https://keynodex.com/docs/chat/messages

Summarize and compress a long chat session to free up context space. The response is streamed via SSE.

```APIDOC
## POST /api/v1/chat/sessions/{session_id}/compact

### Description
Summarize and compress a long session to free context space. Returns an SSE stream.

### Method
POST

### Endpoint
`/api/v1/chat/sessions/{session_id}/compact`
```

--------------------------------

### Get Post View Analytics

Source: https://keynodex.com/docs/analytics/post-views

Retrieve view analytics for the authenticated user's posts. This endpoint is useful for understanding content performance, audience engagement, and optimizing publishing strategies.

```APIDOC
## GET /api/v1/post-views

### Description
Get view analytics for the authenticated user's posts.

### Method
GET

### Endpoint
`/api/v1/analytics/post-views`

### Parameters
#### Query Parameters
- **API Key** - Required - Authentication token to access the API.

### Response
#### Success Response (200)
- **views** (integer) - The total number of views for a post.
- **trends** (object) - An object containing view trends over time.

#### Response Example
{
  "views": 1500,
  "trends": {
    "daily": [
      {"date": "2023-10-26", "views": 100},
      {"date": "2023-10-27", "views": 120}
    ],
    "weekly": [
      {"week": "2023-W43", "views": 700}
    ]
  }
}
```

--------------------------------

### List your posts

Source: https://keynodex.com/docs/content/posts-api

List all posts belonging to the authenticated user, including drafts and published. Returns posts ordered by creation date (newest first).

```APIDOC
## GET /api/v1/posts

### Description
List all posts belonging to the authenticated user, including drafts and published. Returns posts ordered by creation date (newest first).

### Method
GET

### Endpoint
`/api/v1/posts`
```

--------------------------------

### Get a published post

Source: https://keynodex.com/docs/content/public-posts

Retrieve a specific published post using the author's username and the post's slug. This endpoint is useful for displaying individual posts on external platforms.

```APIDOC
## GET /api/v1/public/posts/{username}/{slug}

### Description
Retrieve a published post by the author's username and post slug.

### Method
GET

### Endpoint
/api/v1/public/posts/{username}/{slug}

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the post author.
- **slug** (string) - Required - The URL-safe post identifier.

### Response
#### Success Response (200)
- **title** (string) - Required - Post title.
- **slug** (string) - Required - URL-safe post identifier.
- **bodyMarkdown** (string) - Required - Full post content in Markdown.
- **tags** (string[]) - Required - Topic tags.
- **coverImageUrl** (string) - Required - Cover image URL.
- **suggestedQuestions** (string[]) - Required - AI Representative prompt suggestions for this post.
- **publishedAt** (string (ISO 8601)) - Required - Publication timestamp.
- **author** (object) - Required - Author profile summary.
  - **name** (string) - Required - Author name.
  - **slug** (string) - Required - Author profile slug.
  - **photoUrl** (string) - Required - Author photo URL.
  - **title** (string) - Required - Author professional title.
```

--------------------------------

### Get Profile View Analytics

Source: https://keynodex.com/docs/analytics/profile-views

Retrieves aggregated data about profile views for the authenticated user. This endpoint helps understand profile performance, viewer origins, and conversion rates when combined with other analytics.

```APIDOC
## GET /api/v1/profile-views

### Description
Get profile view analytics for the authenticated user. This endpoint returns aggregated data about who is viewing your profile, when they visit, and how those numbers trend over time.

### Method
GET

### Endpoint
/api/v1/analytics/profile-views

### Parameters
#### Query Parameters
This endpoint does not explicitly list query parameters in the documentation.

#### Request Body
This endpoint does not require a request body.

### Response
#### Success Response (200)
This endpoint returns aggregated data about profile views. Specific fields are not detailed in the provided documentation, but may include view counts, timestamps, and user demographics.

#### Response Example
{
  "example": "response body"
}
```

--------------------------------

### Publish a Profile

Source: https://keynodex.com/docs/profiles/profile-publishing

Use this endpoint to make a profile visible in the public directory and accessible via its URL. Publishing sets the `isPublic` field to true.

```bash
curl -X POST \
  '/api/v1/profiles/{profile_id}/publish' \
  -H 'accept: application/json' \
  -H 'x-api-key: YOUR_API_KEY'
```

--------------------------------

### Execute a UI command

Source: https://keynodex.com/docs/chat/messages

Execute a UI command triggered by the AI Representative, such as navigating to a page or opening a modal. This is typically used when server-side command processing is required.

```APIDOC
## POST /api/v1/chat/command

### Description
Execute a UI command triggered by the AI Representative (e.g. navigate, open modal).

### Method
POST

### Endpoint
`/api/v1/chat/command`
```

--------------------------------

### Ask an AI Representative (Synchronous)

Source: https://keynodex.com/docs/ai-representative/ask-sync

The synchronous ask endpoint sends a question to a professional's AI Representative and returns the complete answer in a single JSON response. No streaming, no event parsing. This is the simplest way to interact with an AI Representative programmatically.

```APIDOC
## POST /api/v1/public/ask-sync

### Description
Ask a question and receive a complete JSON response.

### Method
POST

### Endpoint
`/api/v1/public/ai/ask-sync`

### Parameters
#### Request Body
- **profileId** (string) - Required - The unique identifier of the professional whose AI Representative you want to ask.
- **question** (string) - Required - The question to ask the AI Representative. Maximum 1,000 characters.

### Response
#### Success Response (200)
- **answer** (string) - Required - The AI Representative's complete response to your question.
- **suggested_questions** (string[]) - Required - An array of follow-up questions the AI Representative suggests based on the conversation context.
- **remaining_questions** (number) - Required - The number of questions the visitor has remaining before hitting the rate limit.

### Request Example
```json
{
  "profileId": "clp_12345",
  "question": "What services do you offer?"
}
```

### Response Example
```json
{
  "answer": "I specialize in residential real estate across the greater Miami area. My services include buyer representation, listing and marketing homes for sale, investment property analysis, and relocation assistance. I also offer free market reports for any neighborhood you are interested in.",
  "suggested_questions": [
    "What neighborhoods do you specialize in?",
    "Can you help with investment properties?",
    "How do I get a free market report?"
  ],
  "remaining_questions": 8
}
```

### Error Responses
- **400**: Invalid request body (missing `profileId` or `question`)
- **404**: Profile not found
- **429**: Rate limit exceeded
- **500**: Internal server error

All error responses follow this shape:
```json
{
  "error": "Rate limit exceeded",
  "retryAfter": 30
}
```
```

--------------------------------

### Generate QR Code for Authenticated User

Source: https://keynodex.com/docs/contacts/qr-codes

Generates a QR code image for the authenticated user's profile. Supports customization of format, scale, and colors. Can optionally return JSON with the URL instead of the raw image.

```APIDOC
## GET /api/v1/qr/me

### Description
Generate a QR code image for your own profile.

### Method
GET

### Endpoint
/api/v1/qr/me

### Query Parameters
- **format** (string) - Optional - Image format. Either png or svg. Defaults to png.
- **scale** (number) - Optional - Scale factor from 1 to 20. Higher values produce larger images. Defaults to 5.
- **include_data** (boolean) - Optional - When true, returns JSON with URL instead of raw image. Defaults to false.
- **dark** (string) - Optional - Hex color for the dark modules. Defaults to #000000.
- **light** (string) - Optional - Hex color for the light modules. Defaults to #FFFFFF.

### Response
When `include_data=false` (default), the response is raw binary with the appropriate content type:
  * `Content-Type: image/png` for PNG format
  * `Content-Type: image/svg+xml` for SVG format

When `include_data=true`, the response is JSON:
#### Success Response (200)
- **url** (string) - Required - Direct URL to the generated QR code image.
- **includesData** (boolean) - Required - Confirms data mode was used.
```

--------------------------------

### List memories

Source: https://keynodex.com/docs/chat/memories

Lists all stored memories for the authenticated user. Requires API Key authentication.

```APIDOC
## GET /api/v1/chat/memories

### Description
List all stored memories for the authenticated user.

### Method
GET

### Endpoint
/api/v1/chat/memories

### Authentication
API Key
```

--------------------------------

### Common Errors and Solutions

Source: https://keynodex.com/docs/reference/error-codes

Guidance on diagnosing and resolving common HTTP error codes encountered when interacting with the PingRep API, including specific causes and recommended fixes.

```APIDOC
## Common errors and solutions

### 401 Unauthorized
**Causes:**
  * Missing `Authorization` header
  * Expired JWT token
  * Revoked API key
**Fix:** Include a valid `Authorization: Bearer <token>` header. If using a JWT, check the expiration time and refresh if needed. If using an API key, verify it has not been revoked.

### 403 Forbidden
**Causes:**
  * API key missing the required scope for this endpoint
  * User role does not permit this action in the organization
  * Attempting to modify another user's resource
**Fix:** Check your API key scopes with `GET /api/v1/api-keys/scopes`. For organization actions, verify your role permits the operation.

### 409 Conflict
**Causes:**
  * Creating a profile with a slug that is already taken
  * Inviting a member who is already in the organization
**Fix:** Use a different unique identifier or check for existing resources before creating.

### 410 Gone
**Causes:**
  * Magic link token used after its expiration window
  * One-time token already consumed
**Fix:** Request a new magic link or token. These are single-use and time-limited by design.

### 429 Too Many Requests
**Fix:** Read the `X-RateLimit-Reset` header and wait until the window resets. See Rate Limits for retry strategies and per-tier allowances.
```

--------------------------------

### Generate AI Greeting

Source: https://keynodex.com/docs/profiles/profile-publishing

Generate a personalized AI greeting based on the profile's professional information. The greeting is automatically saved to the profile.

```bash
curl -X POST \
  '/api/v1/profiles/{profile_id}/greeting/generate' \
  -H 'accept: application/json' \
  -H 'x-api-key: YOUR_API_KEY'
```

--------------------------------

### Invite a member

Source: https://keynodex.com/docs/billing/team-management

Send an invitation to add a new member to your organization. The invited user receives a magic link email to accept.

```APIDOC
## POST /api/v1/organizations/{org_id}/members

### Description
Send an invitation to add a new member to your organization. The invited user receives a magic link email to accept.

### Method
POST

### Endpoint
/api/v1/organizations/{org_id}/members

### Authentication
JWT

### Parameters
#### Request Body
- **email** (string) - Required - Email address of the person to invite.
- **role** (string) - Required - Role to assign. Typically "member" or "admin".
```

--------------------------------

### ask_ai_rep

Source: https://keynodex.com/docs/mcp/available-tools

Ask an AI Representative a question about the profile owner. The AI Rep responds based on the professional's identity, experience, and expertise.

```APIDOC
## ask_ai_rep

### Description
Ask an AI Representative a question about the profile owner. The AI Rep responds based on the professional's identity, experience, and expertise.

### Auth
Public

### Parameters
#### Path Parameters
- **profileId** (string) - Required - Profile ID or slug of the person whose AI Rep you want to ask.
- **question** (string) - Required - Your question for the AI Representative. Maximum 500 characters.

### Notes
Questions are limited to 500 characters. Keep them focused for the best responses. The AI Rep draws on the profile owner's professional context to generate relevant answers.
```

--------------------------------

### Save a Contact

Source: https://keynodex.com/docs/contacts/contact-management

Save a new contact from one of the three supported sources: QR scan, web visit, or MCP interaction. Returns the saved contact's ID and details.

```APIDOC
## Save a Contact

### Description
Save a new contact to your contact list from a QR scan, web visit, or MCP interaction.

### Method
POST

### Endpoint
/api/v1/contacts

### Authentication
API Key

### Parameters
#### Request Body
- **profileId** (string (uuid)) - Required - The profile ID of the person you want to save as a contact.
- **source** (string) - Required - How this contact was captured. One of: qr_scan, web, or mcp.

### Response
#### Success Response (200)
- **id** (string) - Required - Unique identifier for this saved contact.
- **profileId** (string (uuid)) - Required - The profile ID of the saved contact.
- **name** (string) - Required - Full name of the contact.
- **title** (string) - Required - Professional title or role.
- **company** (string) - Required - Company or organization name.
- **location** (string) - Required - Geographic location.
- **photoUrl** (string) - Required - URL to the contact's profile photo.
- **savedAt** (string (ISO 8601)) - Required - Timestamp when the contact was saved.

### Request Example
```json
{
  "profileId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "source": "qr_scan"
}
```

### Response Example
```json
{
  "id": "f0e9d8c7-b6a5-4321-0987-654321fedcba",
  "profileId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "name": "Jane Doe",
  "title": "Software Engineer",
  "company": "Tech Corp",
  "location": "San Francisco, CA",
  "photoUrl": "https://example.com/photos/jane.jpg",
  "savedAt": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### Add PingRep MCP Server to Configuration

Source: https://keynodex.com/docs/mcp/claude-desktop

Add the PingRep MCP server configuration to your Claude Desktop's `mcpServers` object. Ensure this entry is added alongside any existing configurations.

```json
{
  "mcpServers": {
    "pingrep": {
      "url": "https://mcp.pingrep.com",
      "apiKey": "YOUR_API_KEY"
    }
  }
}
```

--------------------------------

### Ask an AI Representative (Streaming)

Source: https://keynodex.com/docs/ai-representative/ask

The streaming ask endpoint sends a question to a professional's AI Representative and returns the response as a real-time Server-Sent Events (SSE) stream. This is the primary endpoint for building interactive chat experiences.

```APIDOC
## POST /api/v1/public/ai/ask

### Description
Send a question to an AI Representative and receive a real-time streamed response.

### Method
POST

### Endpoint
`/api/v1/public/ai/ask`

### Parameters
#### Request Body
- **profileId** (string) - Required - The unique identifier of the professional whose AI Representative you want to ask.
- **question** (string) - Required - The question to ask the AI Representative. Maximum 1,000 characters.
- **mode** (string) - Optional - Conversation mode. Use 'public' for visitor interactions or 'owner' for the profile owner interacting with their own AI Rep. Defaults to 'public'. Allowed values: `public`, `owner`
- **visitorFingerprint** (string) - Optional - A unique identifier for the visitor. Used for rate limiting and conversation continuity. Generate a stable fingerprint per device or browser session.
- **sessionId** (string) - Optional - Session identifier for grouping related questions into a single conversation thread.
- **conversationHistory** (array) - Optional - Previous messages in the conversation for multi-turn context. Each entry has a role and content field.
  - **role** (string) - Required - The message author. Either 'user' or 'assistant'.
  - **content** (string) - Required - The message text.
- **postSlug** (string) - Optional - If the question relates to a specific blog post, include the post slug for additional context.
- **exchangeCount** (number) - Optional - The number of question-answer exchanges so far in this session. Used for rate limit tracking.

### SSE event types
The response is a Server-Sent Events stream. Each event has a `type` field that tells you what kind of data it contains.

Event| Description  
---|---  
`connected`| Connection established. The stream is ready.  
`meta`| Metadata about the AI Representative (name, profile info).  
`post_context`| Blog post context loaded, if `postSlug` was provided.  
`text`| A chunk of the AI Representative's response. Concatenate these to build the full answer.  
`error`| An error occurred during generation. Contains an error message.  
`done`| The response is complete. Includes suggested follow-up questions.  

### Error Handling
Errors can arrive in two ways:
  1. **HTTP errors** (4xx, 5xx) before the stream starts, returned as standard JSON error responses.
  2. **Stream errors** during generation, sent as SSE events with `type: "error"`.

Always handle both cases in your integration.

HTTP Status| Meaning  
---|---  
`400`| Invalid request body (missing `profileId` or `question`)  
`404`| Profile not found  
`429`| Rate limit exceeded  
`500`| Internal server error  
```

--------------------------------

### Error Handling Best Practices

Source: https://keynodex.com/docs/reference/error-codes

Recommended strategies for effectively handling errors in client applications interacting with the PingRep API, focusing on status code checking, programmatic validation error parsing, logging, and appropriate retry logic.

```APIDOC
## Error handling best practices
  1. **Always check the status code first.** Branch your logic on the HTTP status before parsing the body.
  2. **Parse validation errors programmatically.** Use the `loc` field to map errors back to specific form fields.
  3. **Log the full response.** Include the status code, headers, and body in your error logs for debugging.
  4. **Do not retry 4xx errors blindly.** Client errors (400, 401, 403, 404, 409, 422) require you to fix the request before retrying. Only 429 and 5xx errors benefit from retries.
```

--------------------------------

### Check usage

Source: https://keynodex.com/docs/reference/api-keys

Monitor how many requests a specific API key has made.

```APIDOC
## GET /api/v1/api-keys/{key_id}/usage

### Description
Returns request counts, last used timestamp, and usage breakdown by endpoint.

### Method
GET

### Endpoint
/api/v1/api-keys/{key_id}/usage

### Parameters
#### Path Parameters
- **key_id** (string) - Required - The ID of the key to check usage for.

### Response
#### Success Response (200)
- **usage** (object) - An object containing request counts, last used timestamp, and usage breakdown by endpoint.
```

--------------------------------

### List keys

Source: https://keynodex.com/docs/reference/api-keys

Retrieve all API keys for the authenticated user. The key value itself is not included in the response for security.

```APIDOC
## GET /api/v1/api-keys

### Description
Retrieve all API keys for the authenticated user. The key value itself is not included in the response for security.

### Method
GET

### Endpoint
/api/v1/api-keys

### Response
#### Success Response (200)
- **keys** (object[]) - An array of API keys with their names, scopes, and status. The key secret is never returned.
```

--------------------------------

### Generate QR Code for a Specific Profile

Source: https://keynodex.com/docs/contacts/qr-codes

Generates a QR code for a specific profile identified by its ID. Supports customization of format, scale, and colors, and can return raw image or JSON with URL.

```APIDOC
## GET /api/v1/qr/{profile_id}

### Description
Generate a QR code for a specific profile.

### Method
GET

### Endpoint
/api/v1/qr/{profile_id}

### Parameters
#### Path Parameters
- **profile_id** (string) - Required - The ID of the profile for which to generate the QR code.

### Query Parameters
- **format** (string) - Optional - Image format. Either png or svg. Defaults to png.
- **scale** (number) - Optional - Scale factor from 1 to 20. Higher values produce larger images. Defaults to 5.
- **include_data** (boolean) - Optional - When true, returns JSON with URL instead of raw image. Defaults to false.
- **dark** (string) - Optional - Hex color for the dark modules. Defaults to #000000.
- **light** (string) - Optional - Hex color for the light modules. Defaults to #FFFFFF.

### Response
When `include_data=false` (default), the response is raw binary with the appropriate content type:
  * `Content-Type: image/png` for PNG format
  * `Content-Type: image/svg+xml` for SVG format

When `include_data=true`, the response is JSON:
#### Success Response (200)
- **url** (string) - Required - Direct URL to the generated QR code image.
- **includesData** (boolean) - Required - Confirms data mode was used.
```

--------------------------------

### Publish a post

Source: https://keynodex.com/docs/content/posts-api

Publish a draft post, making it visible on your public profile.

```APIDOC
## POST /api/v1/posts/{post_id}/publish

### Description
Publish a draft post, making it visible on your public profile.

### Method
POST

### Endpoint
`/api/v1/posts/{post_id}/publish`

#### Path Parameters
- **post_id** (string) - Required - The unique identifier of the post to publish.
```

--------------------------------

### List sessions

Source: https://keynodex.com/docs/chat/sessions

List all chat sessions for the authenticated user. Returns sessions ordered by last activity (most recent first). Use this to build a conversation sidebar or session picker.

```APIDOC
## List sessions

### Description
List all chat sessions for the authenticated user, ordered by last activity.

### Method
GET

### Endpoint
/api/v1/chat/sessions

### Authentication
API Key
```

--------------------------------

### Google OAuth Authentication

Source: https://keynodex.com/docs/getting-started/authentication

Initiate the Google OAuth sign-in flow. Redirect users to the specified endpoint. After signing in with Google, they are redirected back with an authorization code.

```APIDOC
## GET /api/v1/auth/google

### Description
Initiate Google OAuth sign-in flow.

### Method
GET

### Endpoint
/api/v1/auth/google
```

--------------------------------

### get_profile

Source: https://keynodex.com/docs/mcp/available-tools

Look up a professional profile by ID or slug. Returns the full public profile including name, title, company, bio, and social links.

```APIDOC
## get_profile

### Description
Look up a professional profile by ID or slug. Returns the full public profile including name, title, company, bio, and social links.

### Auth
Public

### Parameters
#### Path Parameters
- **profileId** (string) - Required - Profile ID (UUID) or URL slug to look up.
```

--------------------------------

### save_contact

Source: https://keynodex.com/docs/mcp/available-tools

Save a contact to your PingRep contact list. This is the only tool that requires authentication.

```APIDOC
## save_contact

### Description
Save a contact to your PingRep contact list. This is the only tool that requires authentication.

### Auth
API Key Required

### Parameters
#### Path Parameters
- **profileId** (string) - Required - Profile ID of the person to save as a contact.
- **name** (string) - Required - Name of the contact.
- **email** (string) - Required - Email address of the contact.
- **phone** (string) - Optional - Phone number of the contact.
- **notes** (string) - Optional - Notes about this contact. Maximum 500 characters.

### Authentication Required
The `save_contact` tool only works when the MCP server is configured with a valid `PINGREP_API_KEY`. Without it, the tool will return an authentication error.
```

--------------------------------

### Retrieve QR Code URL for Authenticated User

Source: https://keynodex.com/docs/contacts/qr-codes

Retrieves just the URL for your profile QR code without downloading the image.

```APIDOC
## GET /api/v1/qr/me/url

### Description
Get the URL for your profile QR code.

### Method
GET

### Endpoint
/api/v1/qr/me/url
```

--------------------------------

### search_profiles

Source: https://keynodex.com/docs/mcp/available-tools

Search the PingRep professional directory. Filter by keyword, role, location, or any combination.

```APIDOC
## search_profiles

### Description
Search the PingRep professional directory. Filter by keyword, role, location, or any combination.

### Auth
Public

### Parameters
#### Query Parameters
- **query** (string) - Optional - Free-text search query.
- **role** (string) - Optional - Filter by professional role or title.
- **location** (string) - Optional - Filter by geographic location.

### Search Tips
You can combine all three parameters for precise results. Omit parameters you do not need. For example, searching with only `location: "Dubai"` returns all discoverable professionals in Dubai regardless of role.
```

--------------------------------

### Generate AI greeting

Source: https://keynodex.com/docs/profiles/profile-publishing

Generates a personalized AI greeting based on the profile's professional information. This greeting is used by the AI Representative when someone visits the profile.

```APIDOC
## POST /api/v1/profiles/{profile_id}/greeting/generate

### Description
Generate a personalized AI greeting based on the profile's professional information. PingRep uses AI to create a natural, contextual greeting that your AI Representative uses when someone visits your profile. The greeting is generated from your name, title, company, bio, and skills. Each call generates a fresh greeting. The greeting is automatically saved to the profile.

### Method
POST

### Endpoint
/api/v1/profiles/{profile_id}/greeting/generate

### Parameters
#### Path Parameters
- **profile_id** (string) - Required - The unique identifier of the profile for which to generate a greeting.

### Request Example
```json
{
  "example": "No request body needed for this operation."
}
```

### Response
#### Success Response (200)
- **greeting** (string) - The generated AI greeting.
- **message** (string) - Confirmation message indicating the greeting has been generated and saved.

#### Response Example
```json
{
  "greeting": "Hello! I'm [Name], a [Title] at [Company]. I specialize in [Skills].",
  "message": "AI greeting generated and saved successfully."
}
```
```

--------------------------------

### List a user's published posts

Source: https://keynodex.com/docs/content/public-posts

List all published posts for a given user, ordered by publication date (newest first). This is useful for creating content aggregators or displaying a user's posts.

```APIDOC
## GET /api/v1/public/posts/{username}

### Description
List all published posts for a given user. Returns posts ordered by publication date (newest first). Only published posts are included.

### Method
GET

### Endpoint
/api/v1/public/posts/{username}

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the post author.
```

--------------------------------

### List members

Source: https://keynodex.com/docs/billing/team-management

Retrieve all members of an organization including their roles and invitation status.

```APIDOC
## GET /api/v1/organizations/{org_id}/members

### Description
Retrieve all members of an organization including their roles and invitation status.

### Method
GET

### Endpoint
/api/v1/organizations/{org_id}/members

### Authentication
JWT

### Response
#### Success Response (200)
Returns all members and pending invitations for the organization.
```
Tokens:
Raw