Getting Started with the API
=============================

Content Chimera has a REST API that provides programmatic access to migration-ready
transformed content. If you are building a CMS migration pipeline, feeding processed
content into an external tool, or scripting bulk content exports, the API gives you direct
access to your crawled and enriched data.

.. contents:: On this page
   :local:
   :depth: 2


When to Use the API
--------------------

The API is the right choice when you need to:

- Pull processed page content (clean HTML body, metadata, components) into a CMS migration
  tool
- Look up specific pages by URL to retrieve their transformation-ready data
- Export paginated lists of pages with their flattened table fields for external processing

For other programmatic workflows --- such as running crawls, creating charts, building
reports, or querying data --- we recommend the **MCP interface** instead. MCP is
higher-level, easier to work with, and designed for use with AI assistants that can handle
the orchestration for you. See :doc:`quickstart_mcp` for details.


Authentication
---------------

API requests require a Bearer token issued through Laravel Passport.

1. Log in to the Content Chimera web interface.
2. Click your name in the top-right corner and select **API Tokens**.
3. Create a new token and copy it. You will not be able to see it again.

Pass the token in the ``Authorization`` header of every request::

   Authorization: Bearer YOUR_TOKEN


Migration Endpoints
--------------------

The API exposes three endpoints for accessing migration-ready content. In all examples
below, replace ``APP_URL`` with your Content Chimera instance URL (|app_url|),
``YOUR_TOKEN`` with your API token, and ``EXTENT_ID`` with the numeric ID of your extent
(project).

Get a single page
^^^^^^^^^^^^^^^^^^

Retrieve the full processed data for a single page, including its clean HTML body,
extracted components, and metadata.

.. code-block:: bash

   curl -H "Authorization: Bearer YOUR_TOKEN" \
     APP_URL/migration/assets/EXTENT_ID/ASSET_ID

Replace ``ASSET_ID`` with the numeric ID of the processed asset.

Look up a page by URL
^^^^^^^^^^^^^^^^^^^^^^

Find a page by its URL instead of its numeric ID.

.. code-block:: bash

   curl -H "Authorization: Bearer YOUR_TOKEN" \
     "APP_URL/migration/search_url/EXTENT_ID?url=https://example.com/page"

List pages (paginated)
^^^^^^^^^^^^^^^^^^^^^^^

Retrieve a paginated list of pages with their flattened table data.

.. code-block:: bash

   curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     APP_URL/migration/assets/EXTENT_ID


Important Notes
----------------

- **The migration API is focused on content export.** It provides read access to your
  processed crawl data. For analysis, charting, and reporting, use the
  :doc:`MCP interface <quickstart_mcp>` instead.
- **Rate limits and quotas apply.** API usage counts toward the same quotas as the web UI
  and MCP.
- **Tokens are personal.** Each token is tied to your user account and has the same
  permissions you do.