Quickstart

Use the same API for any profile, regardless of its tags.

Authenticate

Get your customer API key and API base URL from the Almanac team. Keep the key on your server, outside source control. Set ALMANAC_API_URL to the supplied API origin, without a trailing slash. The documentation domain is not the API origin.

export ALMANAC_API_URL="https://api.thealmanac.ai"
export ALMANAC_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.

curl "$ALMANAC_API_URL/api/v1/articles/jane-doe" \
  -H "Authorization: Bearer $ALMANAC_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:

curl -X POST "$ALMANAC_API_URL/api/v1/articles" \
  -H "Authorization: Bearer $ALMANAC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: generate-jane-doe-001" \
  -d '{"linkedin_id":"jane-doe"}'

If the article does not exist, this reserves 100 credits and returns 202 with a job_id. If it already exists, the API returns 409 with no charge and no article content:

{
  "code": "article_exists",
  "linkedin_id": "jane-doe",
  "message": "This article already exists. Read it or request an update.",
  "credits_charged": 0
}

Your app or agent can then choose to read it with GET /api/v1/articles/jane-doe for 1 credit, or request fresh research with the update endpoint for 100 credits. 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.

curl "$ALMANAC_API_URL/api/v1/jobs/JOB_ID" \
  -H "Authorization: Bearer $ALMANAC_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 for payment and error handling, or the endpoint reference for full response schemas.

Get started

API reference

Authenticate

Read an article

Generate or update

Collect the result

​Authenticate

​Read an article

​Generate or update

​Collect the result

Authenticate

Read an article

Generate or update

Collect the result