### Authorization Header Examples Source: https://acorny.io/developers Two interchangeable header styles are accepted for authentication on every endpoint. ```http Authorization: Token # Readwise-style ``` ```http Authorization: Bearer # Generic ``` -------------------------------- ### Create Highlights (Readwise-compatible) Source: https://acorny.io/developers Use this endpoint to mirror the public Readwise `highlights` create endpoint. Existing clients can work without modification by pointing to your Acorny instance and using an Acorny token. ```bash curl -X POST https://api.acorny.io/api/v2/highlights/ \ -H "Authorization: Token " \ -H "Content-Type: application/json" \ -d '{ \ "highlights": [ \ { \ "text": "Call me Ishmael.", \ "title": "Moby Dick", \ "author": "Herman Melville", \ "source_url": "https://example.com/moby-dick", \ "highlighted_at": "2020-07-14T20:11:24+00:00", \ "location": 1, \ "location_type": "page", \ "note": "favorite opening line" \ } \ ] \ }' ``` -------------------------------- ### Create highlights (Readwise-compatible) Source: https://acorny.io/developers Mirrors the public Readwise `highlights` create endpoint. Existing clients work without modification by pointing them at your Acorny instance and using an Acorny token. ```APIDOC ## POST /api/v2/highlights/ ### Description Creates highlights in Acorny, compatible with the Readwise API. This endpoint is suitable for clients already integrated with Readwise. ### Method POST ### Endpoint `/api/v2/highlights/` ### Parameters #### Header Parameters - **Authorization** (string) - Required - The Personal Access Token for authentication. Accepts `Token ` or `Bearer ` format. - **Content-Type** (string) - Required - Must be `application/json`. #### Request Body - **highlights** (array) - Required - An array of highlight objects, up to 100 items per request. - **highlights[].text** (string) - Required - The highlight body. - **highlights[].title** (string) - Recommended - Source title; used for deduplication. - **highlights[].author** (string) - Optional - Used for deduplication. - **highlights[].source_url** (string) - Optional - Where the highlight came from; used for deduplication. - **highlights[].highlighted_at** (ISO 8601) - Optional - When the highlight was originally made. - **highlights[].location** (number) - Optional - Page, position, or other numeric locator. - **highlights[].location_type** (string) - Optional - Locator label such as `page` or `location`. - **highlights[].note** (string) - Optional - Your annotation; preserved as-is. - **highlights[].category** (string) - Optional - Readwise book category echoed in the response. - **highlights[].source_type** (string) - Optional - Client source marker; stored as import metadata. - **highlights[].image_url** (string) - Optional - Accepted for compatibility; currently ignored. - **highlights[].highlight_url** (string) - Optional - If provided and matches an existing record, the text may be updated. ### Request Example ```json { "highlights": [ { "text": "Call me Ishmael.", "title": "Moby Dick", "author": "Herman Melville", "source_url": "https://example.com/moby-dick", "highlighted_at": "2020-07-14T20:11:24+00:00", "location": 1, "location_type": "page", "note": "favorite opening line" } ] } ``` ### Response #### Success Response A success response is the Readwise `book` array, including `modified_highlights` and `num_highlights`. ``` -------------------------------- ### Ingest Highlights (Acorny Native) Source: https://acorny.io/developers Use this endpoint to send highlights with rich metadata like source details, tags, and annotations. Ensure you include the 'Idempotency-Key' header for safe retries. ```bash curl -X POST https://api.acorny.io/api/v1/ingest/highlights \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 8f1f3b2a-4f10-4d4d-bf8c-1aa6c8a6e2f1" \ -d '{ "items": [ { "quote": "Call me Ishmael.", "note": "Opening line", "tags": ["literature"], "highlightedAt": "2020-07-14T20:11:24+00:00", "source": { "type": "document", "title": "Moby Dick", "author": "Herman Melville" }, "highlightUrl": "https://example.com/moby-dick#h=1", "clientRef": "my-app:42" } ] }' ``` -------------------------------- ### Create highlights (Acorny native) Source: https://acorny.io/developers Ingest highlights into Acorny using the native contract, which supports richer schemas, tags, structured source metadata, idempotency, and per-item action counts. ```APIDOC ## POST /api/v1/ingest/highlights ### Description The canonical Acorny ingestion contract. Use this when you control both ends and want a richer schema, tags, structured source metadata, idempotency, and per-item action counts. ### Method POST ### Endpoint /api/v1/ingest/highlights ### Parameters #### Request Body - **items** (array) - Required - Up to 100 items per request - **items[].quote** (string) - Required - The highlight body - **items[].source.type** (enum) - Required - `url` / `pdf` / `kindle` / `document` - **items[].source.title** (string) - Required - Title of the source material - **items[].source.author** (string) - Optional - Author of the source material - **items[].source.canonicalUrl** (string) - Optional - Canonical URL used for source identity and deduplication - **items[].source.externalId** (string) - Optional - Stable source ID from your system - **items[].note** (string) - Optional - Your annotation - **items[].tags** (string[]) - Optional - Free-form tags - **items[].highlightedAt** (ISO 8601) - Optional - When you originally made the highlight - **items[].highlightUrl** (string) - Optional - Deep link back to the source - **items[].clientRef** (string) - Optional - Client-side reference stored as import metadata ### Request Example ```json { "items": [ { "quote": "Call me Ishmael.", "note": "Opening line", "tags": ["literature"], "highlightedAt": "2020-07-14T20:11:24+00:00", "source": { "type": "document", "title": "Moby Dick", "author": "Herman Melville" }, "highlightUrl": "https://example.com/moby-dick#h=1", "clientRef": "my-app:42" } ] } ``` ### Headers - **Authorization** (string) - Required - Bearer token - **Content-Type** (string) - Required - application/json - **Idempotency-Key** (string) - Optional - Any UUID for idempotency ### Response #### Success Response (200) - **accepted** (integer) - Number of items accepted - **created** (integer) - Number of items created - **skipped** (integer) - Number of items skipped - **restored** (integer) - Number of items restored - **updated** (integer) - Number of items updated - **failed** (integer) - Number of items failed - **errors** (array) - List of errors encountered #### Response Example ```json { "accepted": 1, "created": 1, "skipped": 0, "restored": 0, "updated": 0, "failed": 0, "errors": [] } ``` ``` -------------------------------- ### Verify Token Endpoint Source: https://acorny.io/developers A lightweight ping endpoint to check client connection status. Returns 204 on success and 401 on failure. ```bash curl -i https://api.acorny.io/api/v2/auth/ \ -H "Authorization: Token " ``` ```text # Expected: HTTP/1.1 204 No Content ``` -------------------------------- ### Verify a token Source: https://acorny.io/developers A lightweight ping endpoint useful for client connection checks. Returns `204 No Content` on success and `401` on failure. ```APIDOC ## GET /api/v2/auth/ ### Description Verifies the provided Personal Access Token by pinging the authentication endpoint. ### Method GET ### Endpoint `/api/v2/auth/` ### Parameters #### Header Parameters - **Authorization** (string) - Required - The Personal Access Token for authentication. Accepts `Token ` or `Bearer ` format. ### Response #### Success Response (204) No Content. Indicates the token is valid. #### Error Response (401) Unauthorized. Indicates an invalid or missing token. ``` -------------------------------- ### Ingestion Response Shape Source: https://acorny.io/developers The API response indicates the status of the ingestion request, detailing accepted, created, skipped, restored, updated, and failed items. ```json { "accepted": 1, "created": 1, "skipped": 0, "restored": 0, "updated": 0, "failed": 0, "errors": [] } ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.