# For agents Source: https://docs.ycpedia.org/agents Find machine-readable documentation and integrate without guessing endpoints or credit usage. Use these resources on this documentation site: * [llms.txt](https://docs.ycpedia.org/llms.txt): page index with descriptions. * [llms-full.txt](https://docs.ycpedia.org/llms-full.txt): full documentation text. * [OpenAPI specification](/openapi.json): endpoints, authentication, and schemas. * Append `.md` to a documentation page URL for Markdown. Mintlify also provides a documentation search MCP endpoint at `https://docs.ycpedia.org/mcp` after this site is published. It searches documentation; API requests still require your customer key and API base URL. ## Integration rules 1. Obtain the API origin and customer key from the team. Do not use the docs domain as the API origin. 2. Read `/api/v1/credits` for the balance and account-specific terms and limits. 3. Use a LinkedIn slug to identify the profile. No tag filter is needed. 4. Preserve the same `Idempotency-Key` when retrying a generation or update request. 5. Handle both generation responses: `200` with an article, or `202` with a job ID. 6. Poll the job for free until `succeeded`, `failed`, or `cancelled`. Use its included result. 7. Keep keys out of prompts, logs, browser code, and committed files. # Get credit balance Source: https://docs.ycpedia.org/api-reference/balance GET /api/v1/credits Free. Returns the shared customer balance and account-specific terms and limits. # Buy credits Source: https://docs.ycpedia.org/api-reference/checkout POST /api/v1/credits/checkout Creates a Stripe checkout URL. Open url to complete payment. Credits are added after payment confirmation, not when this endpoint returns. Read GET /api/v1/credits to confirm the balance. Default purchase range: 10–100,000 credits. # Generate an article Source: https://docs.ycpedia.org/api-reference/generate POST /api/v1/articles If an article already exists, returns it for 1 credit (200). Otherwise reserves 100 credits and starts generation (202). Poll the job for the included result. Failed or cancelled jobs are refunded. Replays of the same idempotency key return the original operation without another charge. # Get a job Source: https://docs.ycpedia.org/api-reference/job GET /api/v1/jobs/{job_id} Free. Returns a job belonging to your customer account. On success, article contains the result snapshot. Repeated polling and reading this snapshot are free. It does not change after later profile updates. # Read an article Source: https://docs.ycpedia.org/api-reference/read GET /api/v1/articles/{linkedin_id} Returns the current article for 1 credit per successful request. Does not start generation. A missing article returns 404 without a charge. # Update an article Source: https://docs.ycpedia.org/api-reference/update POST /api/v1/articles/{linkedin_id}/update Refreshes an existing profile with a new research run for 100 credits. Requires an existing profile. Returns 202 while queued or running; a replay of a terminal job returns 200. Poll the job for the included result. Failed or cancelled jobs are refunded. # Credits and retries Source: https://docs.ycpedia.org/credits-and-retries How credits work, how to buy them, and how to retry safely. ## Credit usage Pricing is agreed individually with your team. Contact us for your account’s terms. | Action | Credits | | ----------------------------- | ------: | | Read an existing article | 1 | | Generate a new article | 100 | | Update an article | 100 | | Poll a job or read its result | 0 | | Check your balance | 0 | Generation and updates include the result. Reading on the website remains free. All API keys for your customer account share one balance. `GET /api/v1/credits` returns your current balance and account-specific terms and limits. ## Buy credits ```bash theme={null} curl -X POST "$YCPEDIA_API_URL/api/v1/credits/checkout" \ -H "Authorization: Bearer $YCPEDIA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"credits":100}' ``` Open the returned `url` to pay. Credits appear after payment is confirmed; creating a checkout does not add credits. Check your balance before starting work. ## Retry safely Send an `Idempotency-Key` on every generate or update request. Use a unique value for each intended operation, and reuse that value when retrying after a timeout or network error. This returns the original operation without another charge. Reusing a key for another profile or operation returns `409`. To deliberately retry a failed job or request a new update, use a new key. Each successful article GET costs 1 credit. For generated results, keep polling the free job endpoint instead. A completed job retains its original article snapshot; use the article endpoint when you need the latest version. ## Errors and limits | Status | What to do | | ------ | ---------------------------------------------------------------------------- | | `401` | Check your API key. | | `402` | Buy credits before retrying. | | `404` | The profile or job is unavailable. A read does not generate it. | | `409` | Wait for active work to finish, or correct a reused idempotency key. | | `422` | Correct the request, including the required idempotency header. | | `429` | Wait for the seconds specified in `Retry-After`. | | `5xx` | Retry with backoff; keep the same idempotency key for generation or updates. | The default limit is **120 requests per minute per customer**, including free requests and all API keys. Error responses contain `detail`, either a message or validation details. Generation and updates reserve credits upfront. Failed or cancelled jobs refund them; the job then reports `credits_charged: 0`. # Quickstart Source: https://docs.ycpedia.org/quickstart Read, generate, and update YCpedia profile articles by LinkedIn ID. Use the same API for any profile, regardless of its tags. ## Authenticate Get your customer API key and API base URL from the YCpedia team. Keep the key on your server, outside source control. Set `YCPEDIA_API_URL` to the supplied API origin, without a trailing slash. The documentation domain is not the API origin. ```bash theme={null} export YCPEDIA_API_URL="https://api.thealmanac.ai" export YCPEDIA_API_KEY="YOUR_API_KEY" ``` Every request needs `Authorization: Bearer YOUR_API_KEY`. ## Read an article Use the slug after `linkedin.com/in/` as the LinkedIn ID. ```bash theme={null} curl "$YCPEDIA_API_URL/api/v1/articles/jane-doe" \ -H "Authorization: Bearer $YCPEDIA_API_KEY" ``` A successful response contains `article` and `credits_charged: 1`. The article includes `title`, `content`, `sources`, `infobox`, version, and timestamps. `content` is the article text with its original formatting; `sources` contains its citations. A missing article returns `404` without a charge. ## Generate or update Generate an article when you need one: ```bash theme={null} curl -X POST "$YCPEDIA_API_URL/api/v1/articles" \ -H "Authorization: Bearer $YCPEDIA_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: generate-jane-doe-001" \ -d '{"linkedin_id":"jane-doe"}' ``` If the article exists, this returns it immediately for **1 credit**. Otherwise, it reserves **100 credits** and returns `202` with a `job_id`. To refresh an existing article, use `POST /api/v1/articles/jane-doe/update` with a new `Idempotency-Key` and no body. An update costs **100 credits**. ## Collect the result Replace `JOB_ID` with the returned job ID. Poll about every 10 seconds while the status is `queued` or `running`. ```bash theme={null} curl "$YCPEDIA_API_URL/api/v1/jobs/JOB_ID" \ -H "Authorization: Bearer $YCPEDIA_API_KEY" ``` When `status` is `succeeded`, use `article` from this response. Polling and reading the job's result are **free**. On `failed` or `cancelled`, stop polling; reserved credits are refunded. See [credits and retries](/credits-and-retries) for payment and error handling, or the [endpoint reference](/api-reference/read) for full response schemas.