People Inc Content API

1. Overview

The People Inc Content API lets licensed clients retrieve the editorial content of any People Inc article as clean, structured markdown. The markdown is suitable for direct ingestion into LLM prompts, RAG pipelines, or any system that benefits from plain-text document representation.

The API exposes two complementary endpoints:

• Content retrieval (GET /v1/markdown) — fetch a known article by canonical URL.
• Search / grounding (POST /v1/search) — ask a natural-language question and receive the best matching licensed articles, ranked and ready for RAG or LLM grounding.

Both endpoints share the same authentication, rate-limit, and error conventions. This guide covers inputs, outputs, and integration patterns for each.

2. Quickstart

Get a key, make one request, read the response. Full details on each step are linked below.

1. Request an API key from the People Inc Content Marketplace team.
2. Pick an endpoint and include the API key in the X-API-Key header (see Authentication):
   • Known article URL → GET /v1/markdown (see Content retrieval)
   • Natural-language question → POST /v1/search (see Search)

Retrieve by URL

# Retrieve an Investopedia article
curl -G https://contentmarketplace.people.inc/v1/markdown \
  --data-urlencode "url=https://www.investopedia.com/how-experts-recommend-managing-a-usd50k-inheritance-for-lasting-financial-securi-12004329" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "status": 200,
  "markdown": "## How Experts Recommend Managing a $50K Inheritance\n\n...",
  "metadata": { /* ... */ }
}

Search by question

# Ground a question with ranked licensed sources
curl -X POST https://contentmarketplace.people.inc/v1/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "question": "best meal prep tips for beginners"
  }'

{
  "question": "best meal prep tips for beginners",
  "documents": [ /* ranked grounding results */ ],
  "selection_summary": { /* ... */ }
}

That's it — you have a working integration. See Getting started checklist for the full pre-launch checklist, including error handling for statuses you'll see in normal operation.

3. Authentication

Every request to either endpoint must include an X-API-Key header containing the API key issued to your organization by the People Inc Content Marketplace team.

A request with a missing or invalid key returns 401 Unauthorized. See Status codes for the full error shape.

4. Rate limits

Each API key is rate limited independently per route. By default, a key may make up to 100 requests per second against each of /v1/markdown and /v1/search. Requests beyond that limit receive a 429 Too Many Requests response.

Every 429 response includes a Retry-After header:

// 429 — rate limit exceeded
HTTP/1.1 429 Too Many Requests
Retry-After: 1

{
  "type": "about:blank",
  "status": 429,
  "title": "Too Many Requests",
  "detail": "Rate limit exceeded. Retry after the period indicated by Retry-After.",
  "instance": "/v1/markdown?url=..."
}

5. Billing

Every successful (200) response from /v1/markdown is recorded as a billable event. 304 Not Modified responses to conditional requests (see Markdown response format) and error responses (4xx/5xx) are not billed.

Billing for /v1/search is governed by your licensing agreement. Contact the Content Marketplace team with questions about search usage or billing.

6. Content retrieval — GET /v1/markdown

Returns the markdown representation of the People Inc article at the given canonical URL.

Query parameters

Request headers

Example request

# Retrieve an Investopedia article
curl -G https://contentmarketplace.people.inc/v1/markdown \
  --data-urlencode "url=https://www.investopedia.com/how-experts-recommend-managing-a-usd50k-inheritance-for-lasting-financial-securi-12004329" \
  -H "X-API-Key: YOUR_API_KEY"

7. Search — POST /v1/search

Accepts a natural-language question and returns ranked, licensed People Inc articles suitable for grounding an AI response. Results include the same clean markdown available from GET /v1/markdown, so a single search call can both discover and retrieve source text.

Request body

Send a JSON object with Content-Type: application/json.

Request headers

Example request

# Search with defaults
curl -X POST https://contentmarketplace.people.inc/v1/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "question": "best meal prep tips for beginners"
  }'

# Search with limit
curl -X POST https://contentmarketplace.people.inc/v1/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "question": "best meal prep tips for beginners",
    "limit": 2
  }'

Response body (200 OK)

The response is a JSON object with these top-level fields:

documents[]

Every entry is a grounding result — use them all.

selection_summary

Example response

{
  "question": "best meal prep tips for beginners",
  "documents": [
    {
      "doc_id": "12345678",
      "domain": "Lifestyle",
      "url": "https://www.allrecipes.com/article/meal-prep-guide/",
      "rank": 1,
      "content": {
        "markdown": "# The Ultimate Guide to Meal Prep for Beginners\n\n...",
        "metadata": {
          "title": "The Ultimate Guide to Meal Prep for Beginners",
          "wordcount": 1850,
          "sourcetype": 0
        }
      }
    }
  ],
  "selection_summary": {
    "selected_count": 5,
    "domain_count": 4,
    "total_wordcount": 1850
  }
}

8. Status codes

9. Markdown response format

200 OK

The response body is a JSON object with the following fields:

metadata fields:

{
  "status": 200,
  "markdown": "## How Experts Recommend Managing a $50K Inheritance\n\n...",
  "metadata": {
    "title": "How Experts Recommend Managing a $50K Inheritance",
    "wordcount": 1240,
    "pubdate": "2023-11-14T22:13:20.000Z",
    "update": "2023-11-16T02:40:00.000Z",
    "author": ["Jane Doe"],
    "language": "en-US",
    "sourcetype": 0,
    "cattax": 9,
    "cat": ["216"],
    "published": 1,
    "provenance": 0,
    "ext": {
      "bylineBlock": ["John Smith, MD"]
    }
  }
}

Every 200 response also includes the following header:

304 Not Modified

When you send an If-None-Match header whose value matches the current ETag, the API responds 304 Not Modified with an empty body. Your previously cached markdown is still current — reuse it. If the content has changed, you instead receive a normal 200 with the updated markdown and a new ETag. This lets polling clients revalidate cheaply without re-downloading unchanged articles.

4xx / 5xx errors

All error responses follow RFC 9457 Problem Details:

// 401 — missing key
{
  "type": "about:blank",
  "status": 401,
  "title": "Unauthorized",
  "detail": "X-API-Key header is required",
  "instance": "/v1/markdown?url=..."
}

// 422 — invalid url parameter
{
  "type": "about:blank",
  "status": 422,
  "title": "Unprocessable Entity",
  "detail": "Invalid request payload",
  "instance": "/v1/markdown?url=not-a-url",
  "errors": [{ "path": ["url"], "message": "Invalid URL", "code": "invalid_format" }]
}

// 404 — article not found
{
  "type": "about:blank",
  "status": 404,
  "title": "Request Error",
  "detail": "Document not found",
  "instance": "/v1/markdown?url=...",
  "requestId": "f75d48b1-9c57-4844-a51b-8027c4fd7260"
}

10. Markdown conventions

The markdown returned by GET /v1/markdown and by documents[].content.markdown on POST /v1/search follows a consistent set of conventions designed for LLM ingestion. Understanding these will help you parse or post-process the content reliably.

Structure

• The article title is rendered as an # (h1) heading at the top of the document.
• Section headings within the article body are ## (h2).
• Callout blocks are rendered as blockquotes, preceded by an ### (h3) label with the callout title — for example ### Tip or ### Key Takeaways.
• Ordered and unordered lists are preserved.
• Tables are rendered in GitHub Flavored Markdown (GFM) pipe-table format.

Images

• Inline images within article body content are suppressed — the markdown contains no image references.

Links

• Hyperlinks within body text are preserved as standard markdown links [text](url).

Whitespace

• Each logical section is separated by a blank line.
• There is no trailing newline at the end of the document.

11. Request & response examples

Successful markdown retrieval

### Request
GET /v1/markdown?url=https%3A%2F%2Fwww.investopedia.com%2Fhow-experts-recommend-managing-a-usd50k-inheritance-for-lasting-financial-securi-12004329
X-API-Key: YOUR_API_KEY

### Response — 200 OK
{
  "status": 200,
  "markdown": "## How Experts Recommend Managing a $50K Inheritance for Lasting Financial Security\n\nInheriting money can feel overwhelming...\n\n### Key Takeaways\n\n> - Consult a fee-only financial advisor before making any moves.\n> - Pay off high-interest debt first.\n\n## What To Do First...",
  "metadata": {
    "title": "How Experts Recommend Managing a $50K Inheritance for Lasting Financial Security",
    "wordcount": 1240,
    "pubdate": "2023-11-14T22:13:20.000Z",
    "update": "2023-11-16T02:40:00.000Z",
    "author": ["Jane Doe"],
    "language": "en-US",
    "sourcetype": 0,
    "cattax": 9,
    "cat": ["216"],
    "published": 1,
    "provenance": 0
  }
}

Conditional request (caching)

The first response returns an ETag. On the next poll, send it back via If-None-Match; if nothing changed you get a 304 with no body and can reuse your cached copy.

### First request
GET /v1/markdown?url=https%3A%2F%2Fwww.investopedia.com%2Fhow-experts-recommend-managing-a-usd50k-inheritance-for-lasting-financial-securi-12004329
X-API-Key: YOUR_API_KEY

### Response — 200 OK
ETag: "d41d8cd98f00b204e9800998ecf8427e"

{ "status": 200, "markdown": "## How Experts Recommend..." }

### Follow-up request — revalidate with the ETag
GET /v1/markdown?url=https%3A%2F%2Fwww.investopedia.com%2Fhow-experts-recommend-managing-a-usd50k-inheritance-for-lasting-financial-securi-12004329
X-API-Key: YOUR_API_KEY
If-None-Match: "d41d8cd98f00b204e9800998ecf8427e"

### Response — 304 Not Modified (empty body; reuse cached markdown)

Successful search

### Request
POST /v1/search
Content-Type: application/json
X-API-Key: YOUR_API_KEY

{
  "question": "best meal prep tips for beginners",
  "limit": 5
}

### Response — 200 OK
{
  "question": "best meal prep tips for beginners",
  "documents": [
    {
      "doc_id": "12345678",
      "url": "https://www.allrecipes.com/article/meal-prep-guide/",
      "domain": "Lifestyle",
      "rank": 1,
      "content": {
        "markdown": "# The Ultimate Guide to Meal Prep for Beginners\n\n...",
        "metadata": { "title": "The Ultimate Guide to Meal Prep for Beginners", "sourcetype": 0 }
      }
    }
  ],
  "selection_summary": {
    "selected_count": 5,
    "domain_count": 4
  }
}

Article moved

### Request
GET /v1/markdown?url=https%3A%2F%2Fwww.investopedia.com%2Fold-article-slug-12345
X-API-Key: YOUR_API_KEY

### Response — 404 Not Found
{
  "type":        "about:blank",
  "status":      404,
  "title":       "Not Found",
  "detail":      "Document has moved",
  "instance":    "/v1/markdown?url=...",
  "redirectUrl": "/v1/markdown?url=https%3A%2F%2Fwww.investopedia.com%2Fnew-article-slug-12345"
}

Article not found

### Response — 404 Not Found
{
  "type":      "about:blank",
  "status":    404,
  "title":     "Request Error",
  "detail":    "Document not found",
  "instance":  "/v1/markdown?url=...",
  "requestId": "f75d48b1-9c57-4844-a51b-8027c4fd7260"
}

Example client wrapper (TypeScript)

// Minimal typed wrapper — adapt baseUrl and key storage to your environment
const BASE_URL = "https://contentmarketplace.people.inc";

interface ArticleMetadata {
  title?: string;
  wordcount?: number;
  pubdate?: string;
  update?: string;
  author?: string[];
  language: string;
  sourcetype: number;
  cattax?: number;
  cat?: string[];
  published?: number;
  provenance?: number;
  ext?: { bylineBlock?: string[] };
}

interface ArticleResponse {
  status: number;
  markdown: string;
  metadata: ArticleMetadata;
}

// Thrown instead of a plain Error when the article has moved, so callers can
// branch on it explicitly rather than have the redirect silently followed.
// A redirect can mean the requested article was replaced, corrected, or taken
// down (e.g. under embargo) — the content at redirectUrl is not guaranteed to
// be "the same article". If the caller is acting on a human's behalf (for
// example, an LLM agent), confirm with the human before re-requesting rather
// than assuming the new URL satisfies their original request.
class ArticleMovedError extends Error {
  constructor(public readonly redirectUrl: string) {
    super(`Article moved: ${redirectUrl}`);
  }
}

async function getArticle(articleUrl: string, apiKey: string): Promise<ArticleResponse> {
  const endpoint = new URL("/v1/markdown", BASE_URL);
  endpoint.searchParams.set("url", articleUrl);

  const response = await fetch(endpoint.toString(), {
    headers: { "X-API-Key": apiKey },
  });

  if (!response.ok) {
    const err = await response.json();

    if (err.redirectUrl) {
      throw new ArticleMovedError(new URL(err.redirectUrl, BASE_URL).toString());
    }

    throw new Error(`[${response.status}] ${err.detail ?? err.title}`);
  }

  return response.json();
}

// Caller decides whether to re-request — do not do this automatically.
try {
  const article = await getArticle("https://www.example.com/old-article-slug", apiKey);
} catch (err) {
  if (err instanceof ArticleMovedError) {
    // Confirm with the user before fetching err.redirectUrl.
  }
}

12. Error handling guidance

Retries

5xx responses are safe to retry. Use exponential backoff with jitter, starting at 1 second and capping at 30 seconds. Do not retry 4xx responses — they indicate a problem with the request itself.

Moved articles

When an article's canonical URL has changed, the API responds 404 with a redirectUrl field in the Problem Details body (see section 9) rather than issuing an HTTP redirect. Check for this field on every 404 response.

URL encoding

The url query parameter must be percent-encoded. Use your language's standard URI encoding function (encodeURIComponent in JavaScript, urllib.parse.quote in Python, etc.) rather than encoding it manually. A common mistake is passing the URL unencoded, which causes the article URL's path to be misinterpreted as part of the request path.

13. Getting started checklist

1. Request an API key from the People Inc Content Marketplace team.
2. Make a test GET /v1/markdown request using the curl example in section 6 with a known article URL. Verify a 200 with a non-empty markdown field.
3. Make a test POST /v1/search request using the curl example in section 7. Verify a 200 with at least one documents entry.
4. Integrate the X-API-Key header into your HTTP client — ensure the key is read from an environment variable or secrets manager, not hardcoded.
5. Handle the status codes documented in section 8, particularly 404s on markdown (check for a redirectUrl before treating them as not-found), 403 not-licensed, 422 validation errors, and 429 rate-limiting, which will occur in normal operation.

14. Contact

For any questions or support, please contact the People Inc Content Marketplace team at [email protected].