CitedEvidenceResearch APIs

/v1/ce — citedevidence extensions

Slug resolver, sitemap, counts, healthcheck, and JSON-LD helpers layered on top of the compatibility surface.

Everything under /v1/ce/ is additional to the compatibility /v1/oa/surface and is driven by citedevidence.com's migration off its local author / institution mirror. Same auth, same rate limits, same envelope shape as /v1/oa/.

Slugs are deterministic {slugified-name}-{md5[:10]→base36[:8]}. See docs/ce-api-integration.md for the reference algorithm; the Go port (services/api/cmd/api/ce_slug.go) is byte-for-byte equivalent and covered by test vectors in ce_slug_test.go.

Slug resolver

  • GET/v1/ce/resolve/slug?entity={authors|institutions|works}&slug={slug}

    Resolve a single slug. Returns 200 on live match, 200 + merged_into on merge, 200 + canonical_redirect on alias, 404 otherwise.

  • POST/v1/ce/resolve/slug/batch

    Batch-resolve up to 500 ids or slugs per request. Unknown inputs return { error: 'not_found' } so callers can distinguish miss from omission.

Sitemap

  • GET/v1/ce/sitemap/{authors|institutions|works}?page=N&per_page=50000

    Paginated, stable-order (openalex_id ASC) batches. Cacheable 24h (Cache-Control + strong ETag tied to the page's max updated_date).

Counts & health

  • GET/v1/ce/counts/{authors|institutions|works|sources|funders|publishers}

    Cheap, 10-minute-cached row count. Uses pg_class.reltuples with COUNT(*) fallback.

  • GET/v1/ce/healthz

    {status, ingest counts per entity, ingest_lag_seconds, rate_limit_tiers}. Safe for public monitoring.

Schema.org helpers

  • GET/v1/ce/{authors|institutions|works}/{id}/jsonld

    Minimal JSON-LD (Person / Organization / ScholarlyArticle) ready to embed in <script type="application/ld+json">.

Admin (operator-only)

  • POST/v1/admin/ce/backfill-slugs?entity={authors|institutions|works}

    One-shot slug backfill using core.ce_backfill_slugs(). Idempotent. Run once per entity after deploying migration 0044.

Merged-entity hints (applies to /v1/oa as well)

  • GET/v1/oa/authors/{retiredId}

    Returns 200 with { status: 'merged', result: { openalex_id, merged_into, canonical_url } } when the record was merged into a successor. Same behavior on /v1/oa/institutions and /v1/oa/works.