Octothorpe Protocol

https://docs.octothorp.es/
Admin
Octothorpe Protocol is a lightweight, distributed system for creating hashtags, backlinks, and link...
Tokens:40,197
Snippets:382
Trust Score:7.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### Blobjects/Everything response example

Source: https://docs.octothorp.es/op-api

Example response from the Blobjects/Everything endpoint. Each result includes @id, title, description, image, date, postDate, and octothorpes array.

```json
{
  "results": [
    {
      "@id": "https://demo.ideastore.dev/multi-platform",
      "title": "Octothorpe Anywhere - Octothorpes Demo",
      "description": "Implementing Octothorpes is really easy. Here are some sites on other platforms that already have it.",
      "image": "https://demo.ideastore.dev/assets/preview.jpg",
      "date": 1740179856134,
      "postDate": 1718445600000,
      "octothorpes": [
        "demo",
        "wordpress"
      ]
    },
    {
      "@id": "https://demo.ideastore.dev/assertions",
      "title": "Assertions - Octothorpes Demo",
      "description": "Statements about urls other than the page you're on are called Assertions",
      "image": null,
      "date": 1740180203218,
      "octothorpes": [
        "etymology",
        "oof",
        "assertions",
        "octothorpe"
      ]
    },
    {
      "@id": "https://demo.ideastore.dev/page%20with%20spaces",
      "title": "Page with Spaces in URL - Octothorpes Demo",
      "description": "This page uses an alternate server, which can easily be set with a page variable.",
      "image": null,
      "date": 1740190020861,
      "octothorpes": [
        "testing",
        "demo"
      ]
    },
    ...
    ]
}
```

--------------------------------

### Terms List response example

Source: https://docs.octothorp.es/op-api

Example response from the Terms List endpoint. Each result includes a term and its date.

```json
{
  "results": [
    {
      "term": "octothorpes",
      "date": 1756497115926
    },
    {
      "term": "demo",
      "date": 1756497115942
    }
  ]
}
```

--------------------------------

### Pages List response example

Source: https://docs.octothorp.es/op-api

Example response from the Pages List endpoint. Each result includes uri, title, description, date, postDate, and image.

```json
{
  "results": [
    {
      "uri": "https://demo.ideastore.dev/multi-platform",
      "title": "Octothorpe Anywhere - Octothorpes Demo",
      "description": "Lorem!.",
      "date": 1740179856134,
      "postDate": 1718445600000,
      "image": "https://demo.ideastore.dev/assets/preview.jpg"
    },
    {
      "uri": "https://demo.ideastore.dev/assertions",
      "title": "Assertions - Octothorpes Demo",
      "description": "Lorem ipsum",
      "date": 1740180203218,
      "postDate": null,
      "image": null
    }
  ]
}
```

--------------------------------

### GET /

Source: https://docs.octothorp.es/op-api

The root endpoint of the OP API. It provides an overview of the API and its capabilities.

```APIDOC
## GET /

### Description
The root endpoint of the OP API. It provides an overview of the API and its capabilities.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **body** (object) - Overview of the API.

#### Response Example
{
  "overview": "The OP API"
}
```

--------------------------------

### Success Response (200 OK)

Source: https://docs.octothorp.es/actively-request-indexing

Example success response returned with HTTP 200 OK. Contains the indexed URI and a timestamp.

```json
{
  "status": "success",
  "message": "Page indexed successfully",
  "uri": "https://yourdomain.com/your-page",
  "indexed_at": 1706024142000
}
```

--------------------------------

### GET /get/pages/posted

Source: https://docs.octothorp.es/op-api

Retrieves a list of pages with 'postDate' and 'image' metadata. Returns a simplified page list.

```APIDOC
## [GET] /get/pages/posted

### Description
Retrieves a list of pages with 'postDate' and 'image' metadata. Returns a simplified page list.

### Method
GET

### Endpoint
https://octothorp.es/get/pages/posted

### Parameters
#### Query Parameters
- **s** (string) - Required - The domain or URL to filter by (e.g., demo).

### Request Example
https://octothorp.es/get/pages/posted?s=demo

### Response
#### Success Response (200)
Returns a JSON object with a 'results' array containing page objects with fields such as 'uri', 'title', 'description', 'date', 'postDate', and 'image'.

#### Response Example
{
  "results": [
    {
      "uri": "https://demo.ideastore.dev/multi-platform",
      "title": "Octothorpe Anywhere - Octothorpes Demo",
      "description": "Lorem!",
      "date": 1740179856134,
      "postDate": 1718445600000,
      "image": "https://demo.ideastore.dev/assets/preview.jpg"
    }
  ]
}
```

--------------------------------

### GET /get/everything/posted

Source: https://docs.octothorp.es/op-api

Retrieves all pages with a 'postDate' (publication date) and 'image' metadata. Results are sorted by postDate when present.

```APIDOC
## [GET] /get/everything/posted

### Description
Retrieves all pages with a 'postDate' (publication date) and 'image' metadata. Results are sorted by postDate when present.

### Method
GET

### Endpoint
https://octothorp.es/get/everything/posted

### Parameters
#### Query Parameters
- **s** (string) - Required - The domain or URL to filter by (e.g., demo).

### Request Example
https://octothorp.es/get/everything/posted?s=demo

### Response
#### Success Response (200)
Returns a JSON object with a 'results' array containing blobjects (pages) with fields such as '@id', 'title', 'description', 'image', 'date', 'postDate', and 'octothorpes'.

#### Response Example
{
  "results": [
    {
      "@id": "https://demo.ideastore.dev/multi-platform",
      "title": "Octothorpe Anywhere - Octothorpes Demo",
      "description": "Implementing Octothorpes is really easy. Here are some sites on other platforms that already have it.",
      "image": "https://demo.ideastore.dev/assets/preview.jpg",
      "date": 1740179856134,
      "postDate": 1718445600000,
      "octothorpes": ["demo", "wordpress"]
    }
  ]
}
```

--------------------------------

### GET /[what]/[by]/[[as]]

Source: https://docs.octothorp.es/op-api

The main query endpoint for retrieving blobjects (e.g., pages, bookmarks) based on data type, query method, and optional output format. Supports filtering via query parameters.

```APIDOC
## GET /[what]/[by]/[[as]]

### Description
The main query endpoint for retrieving blobjects (e.g., pages, bookmarks) based on data type, query method, and optional output format. Supports filtering via query parameters.

### Method
GET

### Endpoint
/[what]/[by]/[[as]]

### Parameters
#### Path Parameters
- **what** (string) - Required - The data type to query (e.g., 'pages', 'bookmarks').
- **by** (string) - Required - The query method (e.g., 'tag', 'domain', 'webring').
- **as** (string) - Optional - The output format (e.g., 'json', 'rss').

#### Query Parameters
- **match** (string) - Optional - Matching strategy (e.g., 'exact', 'fuzzy').
- **when** (string) - Optional - Date filter (e.g., 'today', 'last_week').
- **tag** (string) - Optional - Filter by tag.
- **domain** (string) - Optional - Filter by domain.
- **hashtag** (string) - Optional - Filter by hashtag.

### Request Example
GET /pages/tag/demo?match=fuzzy

### Response
#### Success Response (200)
- **items** (array) - List of blobjects matching the query.

#### Response Example
{
  "items": [
    {
      "url": "https://example.com/page1",
      "title": "Example Page"
    }
  ]
}
```

--------------------------------

### GET /get/[what]/[by]/[[as]]

Source: https://docs.octothorp.es/op-api

The main API endpoint for retrieving data from Octothorp.es. The [what] parameter specifies the data type (everything, pages, thorpes, domains), [by] specifies the query method (thorped, linked, backlinked, bookmarked, posted, in-webring), and optional [as] specifies the output format (json, rss, debug).

```APIDOC
## GET /get/[what]/[by]/[[as]]

### Description
The main API endpoint for retrieving data from Octothorp.es. The [what] parameter specifies the data type (everything, pages, thorpes, domains), [by] specifies the query method (thorped, linked, backlinked, bookmarked, posted, in-webring), and optional [as] specifies the output format (json, rss, debug).

### Method
GET

### Endpoint
`https://octothorp.es/get/[what]/[by]/[[as]]`

### Parameters
#### Path Parameters
- **what** (string) - Required - The type of data to retrieve. Valid values: `everything`, `pages`, `thorpes`, `domains`.
- **by** (string) - Required - The query method to filter or match data. Valid values: `thorped`, `linked`, `backlinked`, `bookmarked`, `posted`, `in-webring`.
- **as** (string) - Optional - The output format. Defaults to `json`. Valid values: `json`, `rss`, `debug`.

### Query Parameters
- **s** (string) - Optional - A search or filter parameter, as shown in examples like `?s=demo`.

### Request Example
`https://octothorp.es/get/everything/posted?s=demo`

### Response
#### Success Response (200)
- For `everything`: Returns blobjects - structured JSON objects containing URI-level data for pages and their octothorpes with attached information (type: link, backlink, etc.).
- For `pages`, `thorpes`, `domains`: Returns a flat list of matching pages and data that applies directly to their URL.

#### Response Example
(No explicit response example provided in the source.)

### Error Handling
(No explicit error handling documented in the source.)
```

--------------------------------

### GET /get/everything/members

Source: https://docs.octothorp.es/op-api

Retrieves pages in a webring hashtagged with a specified tag. The 's' parameter specifies the webring URL and 'o' specifies the tag.

```APIDOC
## [GET] /get/everything/members

### Description
Retrieves pages in a webring hashtagged with a specified tag.

### Method
GET

### Endpoint
https://octothorp.es/get/everything/members

### Parameters
#### Query Parameters
- **s** (string) - Required - The webring URL.
- **o** (string) - Required - The octothorpe tag to filter by.

### Request Example
https://octothorp.es/get/everything/members?s=https://demo.ideastore.dev/demo-webring&o=demo

### Response
#### Success Response (200)
Returns a JSON object with a 'results' array containing blobjects (pages) with fields such as '@id', 'title', 'description', 'image', 'date', 'postDate', and 'octothorpes'.

#### Response Example
{
  "results": [
    {
      "@id": "https://demo.ideastore.dev/multi-platform",
      "title": "Octothorpe Anywhere - Octothorpes Demo",
      "description": "Implementing Octothorpes is really easy. Here are some sites on other platforms that already have it.",
      "image": "https://demo.ideastore.dev/assets/preview.jpg",
      "date": 1740179856134,
      "postDate": 1718445600000,
      "octothorpes": ["demo", "wordpress"]
    }
  ]
}
```

--------------------------------

### Request indexing with link tag

Source: https://docs.octothorp.es/join-server

Add this link tag to the document's head element to request indexing from an Octothorpe server. Replace OP-SERVER with the server URL (e.g., https://octothorp.es) and PAGE with the URL of the page to be indexed. The tag sends a GET request to the server's index endpoint with the uri query parameter.

```html
<link rel="preload" as="fetch" href="OP-SERVER/?uri=PAGE">
```

--------------------------------

### Build the components

Source: https://docs.octothorp.es/web-components/building

Builds the web components. The output is placed in static/components/your-component.js and served automatically by SvelteKit.

```bash
npm run build:components
```

--------------------------------

### Demo HTML file for testing

Source: https://docs.octothorp.es/web-components/building

Create this HTML file in static/components/ to test your component. Run npm run dev and open the given URL.

```html
<!DOCTYPE html>
<html lang="en">
<head><meta charset="UTF-8"><title>Your Component</title></head>
<body>
  <your-component o="test" autoload></your-component>
  <script type="module" src="/components/your-component.js"></script>
</body>
</html>
```

--------------------------------

### GET /debug

Source: https://docs.octothorp.es/op-api

Endpoint to debug a query, returning detailed information about the query processing.

```APIDOC
## GET /debug

### Description
Endpoint to debug a query, returning detailed information about the query processing.

### Method
GET

### Endpoint
/debug

### Parameters
#### Query Parameters
- **query** (string) - Required - The query to debug.

### Request Example
GET /debug?query=pages/tag/demo

### Response
#### Success Response (200)
- **debug** (object) - Debug information.

#### Response Example
{
  "debug": {
    "query": "pages/tag/demo",
    "steps": []
  }
}
```

--------------------------------

### GET /get/everything/thorped

Source: https://docs.octothorp.es/op-api

Retrieves all pages tagged with a specified octothorpe. The 'o' parameter specifies the tag to filter by.

```APIDOC
## [GET] /get/everything/thorped

### Description
Retrieves all pages tagged with a specified octothorpe.

### Method
GET

### Endpoint
https://octothorp.es/get/everything/thorped

### Parameters
#### Query Parameters
- **o** (string) - Required - The octothorpe tag to filter by.

### Request Example
https://octothorp.es/get/everything/thorped?o=demo

### Response
#### Success Response (200)
Returns a JSON object with a 'results' array containing blobjects (pages) with fields such as '@id', 'title', 'description', 'image', 'date', 'postDate', and 'octothorpes'.

#### Response Example
{
  "results": [
    {
      "@id": "https://demo.ideastore.dev/multi-platform",
      "title": "Octothorpe Anywhere - Octothorpes Demo",
      "description": "Implementing Octothorpes is really easy. Here are some sites on other platforms that already have it.",
      "image": "https://demo.ideastore.dev/assets/preview.jpg",
      "date": 1740179856134,
      "postDate": 1718445600000,
      "octothorpes": ["demo", "wordpress"]
    }
  ]
}
```

--------------------------------

### Use octo-badge web component

Source: https://docs.octothorp.es/image-indexing

Load the `<octo-badge>` web component and then use it in your page. The component automatically infers the OP server from the script's URL, so no `server` attribute is needed when loading from your own OP server.

```html
<script type="module" src="https://octothorp.es/components/octo-badge.js"></script>
```

```html
<octo-badge></octo-badge>
```

--------------------------------

### Create and use OctoQuery store

Source: https://docs.octothorp.es/web-components/building

Creates a Svelte store with reactive state (results, loading, error, count) and fetches data using the same parameters as HTML attributes.

```javascript
import { createOctoQuery } from '../shared/octo-store.js';

const query = createOctoQuery('pages', 'thorped');

await query.fetch({ server: 'https://your-op-server.example.com', o: 'demo', limit: 10 });

$query.results  // Array of result objects
$query.loading  // Boolean
$query.error    // String or null
$query.count    // Number of results
```

--------------------------------

### GET /get/thorpes/posted

Source: https://docs.octothorp.es/op-api

Retrieves a list of terms (octothorpes) associated with a given URL, along with their indexing dates.

```APIDOC
## [GET] /get/thorpes/posted

### Description
Retrieves a list of terms (octothorpes) associated with a given URL, along with their indexing dates.

### Method
GET

### Endpoint
https://octothorp.es/get/thorpes/posted

### Parameters
#### Query Parameters
- **s** (string) - Required - The URL to get terms for.

### Request Example
https://octothorp.es/get/thorpes/posted?s=https://demo.ideastore.dev

### Response
#### Success Response (200)
Returns a JSON object with a 'results' array containing term objects with fields 'term' and 'date'.

#### Response Example
{
  "results": [
    {
      "term": "octothorpes",
      "date": 1756497115926
    },
    {
      "term": "demo",
      "date": 1756497115942
    }
  ]
}
```

--------------------------------

### Copy the component template

Source: https://docs.octothorp.es/web-components/building

Copies the shared component template to a new component file. Replace 'your-component' and 'YourComponent' with your actual component names.

```bash
cp src/lib/web-components/shared/COMPONENT_TEMPLATE.svelte \
   src/lib/web-components/your-component/YourComponent.svelte
```

--------------------------------

### GET /get/pages/linked

Source: https://docs.octothorp.es/web-components/components

Retrieves pages that link to a given URL. This endpoint is used by the octo-backlinks component to fetch and display backlinks.

```APIDOC
## GET /get/pages/linked

### Description
Retrieves pages that link to a given URL. This endpoint is used by the octo-backlinks component to fetch and display backlinks.

### Method
GET

### Endpoint
/get/pages/linked

### Parameters
#### Query Parameters
- **o** (string) - Optional - The URL to find backlinks for. Defaults to the current page if omitted.

### Request Example
```
GET /get/pages/linked?o=https://example.com/page
```

### Response
#### Success Response (200)
- **pages** (array) - List of pages linking to the given URL.

#### Response Example
```json
{
  "pages": [
    {
      "url": "https://example.com/backlink",
      "title": "Backlink Page"
    }
  ]
}
```
```

--------------------------------

### Pre-endorse a domain with rel="octo:endorses"

Source: https://docs.octothorp.es/backlinks

Add this link to the head of any page on your domain to endorse an incoming domain. Incoming links from that domain will automatically turn into backlinks. Endorsement only works at the domain level.

```html
<link rel="octo:endorses" href="https://originating-site.com">
```

--------------------------------

### octo-badge with uri and as attributes

Source: https://docs.octothorp.es/image-indexing

Override the `uri` parameter with the `uri` attribute and specify a harmonizer with the `as` attribute. You can still pass `server="https://other-op-server.example"` to point a single badge at a different server.

```html
<octo-badge uri="https://example.com/my-page" as="harmonizer-name"></octo-badge>
```

--------------------------------

### GET /get/everything/thorped/rss

Source: https://docs.octothorp.es/op-api

Retrieves an RSS feed of tagged content. The 'o' parameter specifies the tag and 'limit' specifies the number of items.

```APIDOC
## [GET] /get/everything/thorped/rss

### Description
Retrieves an RSS feed of tagged content.

### Method
GET

### Endpoint
https://octothorp.es/get/everything/thorped/rss

### Parameters
#### Query Parameters
- **o** (string) - Required - The octothorpe tag to filter by.
- **limit** (integer) - Optional - The maximum number of items to return.

### Request Example
https://octothorp.es/get/everything/thorped/rss?o=demo&limit=20

### Response
#### Success Response (200)
Returns an RSS feed (XML) of the tagged content.
```

--------------------------------

### Preload fetch request to OP server

Source: https://docs.octothorp.es/blog/neocities-fix

Use this HTML link tag to send the current page URL to the OP server. The `fetch` preload is blocked by Neocities' security protocol, so replace `fetch` with `image` to avoid the block.

```html
<link rel="preload" as="fetch" href="https://octothorp.es/?uri=https://YOURDOMAIN.COM/PATH/TO/CURRENT/PAGE">
```

--------------------------------

### GET /get/pages/thorped

Source: https://docs.octothorp.es/web-components/components

Retrieves pages tagged with a given octothorpe term. This endpoint is used by the octo-thorpe component to fetch and display tagged pages.

```APIDOC
## GET /get/pages/thorped

### Description
Retrieves pages tagged with a given octothorpe term. This endpoint is used by the octo-thorpe component to fetch and display tagged pages.

### Method
GET

### Endpoint
/get/pages/thorped

### Parameters
#### Query Parameters
- **o** (string) - Required - The octothorpe tag or comma-separated list of tags to filter pages by.

### Request Example
```
GET /get/pages/thorped?o=your-tag
```

### Response
#### Success Response (200)
- **pages** (array) - List of pages matching the tag.

#### Response Example
```json
{
  "pages": [
    {
      "url": "https://example.com/page1",
      "title": "Page 1"
    }
  ]
}
```
```

--------------------------------

### Endorse all domains with wildcard href="*"

Source: https://docs.octothorp.es/backlinks

Use a wildcard in the href to endorse backlinks from any site connected to your servers. This automatically turns all incoming links from any domain into backlinks.

```html
<link rel="octo:endorses" href="*">
```

--------------------------------

### Preload link to use keywords harmonizer

Source: https://docs.octothorp.es/harmonizers

Indexes a page using the harmonizer named 'keywords' by fetching the OP-SERVER with the page URI and 'as=keywords'. Any rules present there override the same rules in the default harmonizer.

```html
<link rel="preload" as="fetch" href="OP-SERVER/?uri=PAGE&as=keywords">
```

--------------------------------

### GET /get/everything/thorped/debug

Source: https://docs.octothorp.es/op-api

Debug a query. Returns the MultiPass created from the request params, the literal SPARQL query generated from the MultiPass, and the actual results of the query.

```APIDOC
## [GET] /get/everything/thorped/debug

### Description
Debug a query. Returns the MultiPass created from the request params, the literal SPARQL query generated from the MultiPass, and the actual results of the query.

### Method
GET

### Endpoint
https://octothorp.es/get/everything/thorped/debug

### Parameters
#### Query Parameters
- **o** (string) - Required - The octothorpe tag to filter by.
- **match** (string) - Optional - The matching mode (e.g., 'fuzzy').

### Request Example
https://octothorp.es/get/everything/thorped/debug?o=demo&match=fuzzy

### Response
#### Success Response (200)
Returns a JSON object with the following structure:
{
  "results": {
    "multiPass": {},
    "query": {},
    "actualResults": {}
  }
}
```

--------------------------------

### Request Indexing with JSON (curl)

Source: https://docs.octothorp.es/actively-request-indexing

Recommended way to request indexing using JSON. The `harmonizer` field is optional and can specify a remote harmonizer URL.

```bash
curl -X POST https://octothorp.es/index \
  -H "Origin: https://yourdomain.com" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "https://yourdomain.com/your-page",
    "harmonizer": "https://yourdomain.com/custom-harmonizer.json"
  }'
```

--------------------------------

### GET /get/pages/linked

Source: https://docs.octothorp.es/op-api

Retrieves pages that link to any page on a specified domain. Using a domain string performs a fuzzy match, returning results for all URLs on that domain.

```APIDOC
## [GET] /get/pages/linked

### Description
Retrieves pages that link to any page on a specified domain. Using a domain string performs a fuzzy match, returning results for all URLs on that domain.

### Method
GET

### Endpoint
https://octothorp.es/get/pages/linked

### Parameters
#### Query Parameters
- **o** (string) - Required - The domain to filter by (e.g., demo.ideastore.dev).

### Request Example
https://octothorp.es/get/pages/linked?o=demo.ideastore.dev

### Response
#### Success Response (200)
Returns a JSON object with a 'results' array containing page objects with fields such as 'uri', 'title', 'description', 'date', 'postDate', and 'image'.

#### Response Example
{
  "results": [
    {
      "uri": "https://demo.ideastore.dev/multi-platform",
      "title": "Octothorpe Anywhere - Octothorpes Demo",
      "description": "Lorem!",
      "date": 1740179856134,
      "postDate": 1718445600000,
      "image": "https://demo.ideastore.dev/assets/preview.jpg"
    }
  ]
}
```

--------------------------------

### GET /get/pages/{author}/multipass

Source: https://docs.octothorp.es/multipass

Retrieves a MultiPass JSON object for a given API request by appending /multipass to the URL. The response can be saved, shared, or passed to a component.

```APIDOC
## GET /get/pages/{author}/multipass

### Description
Retrieves a MultiPass JSON object for a given API request by appending /multipass to the URL. The response can be saved, shared, or passed to a component.

### Method
GET

### Endpoint
https://octothorp.es/get/pages/{author}/multipass

### Parameters
#### Path Parameters
- **author** (string) - Required - The author identifier for the pages query.

#### Query Parameters
- **o** (string) - Optional - Example: demo. Additional query parameters as per the API request.

### Request Example
https://octothorp.es/get/pages/thorped/multipass?o=demo

### Response
#### Success Response (200)
- **meta** (object) - Metadata about the MultiPass.
- **subjects** (object) - Subject query configuration.
- **objects** (object) - Object query configuration.
- **filters** (object) - Filter settings.

#### Response Example
{
  "meta": {
    "title": "string",
    "description": "string",
    "server": "https://octothorp.es/",
    "author": "string",
    "image": "url",
    "version": "1",
    "resultMode": "blobjects | links | octothorpes | domains"
  },
  "subjects": {
    "mode": "exact | fuzzy | byParent",
    "include": [],
    "exclude": []
  },
  "objects": {
    "type": "termsOnly | pagesOnly | notTerms | all | none",
    "mode": "exact | fuzzy | very-fuzzy",
    "include": [],
    "exclude": []
  },
  "filters": {
    "subtype": "Backlink | Cite | Bookmark | null",
    "limitResults": "100",
    "offsetResults": "0",
    "dateRange": {
      "after": 1704067200,
      "before": 1735689600
    }
  }
}
```

--------------------------------

### Get a MultiPass by adding /multipass to an API URL

Source: https://docs.octothorp.es/multipass

Add /multipass as the format segment of any API URL to receive a MultiPass JSON object that can be saved, shared, or passed to a component.

```text
https://octothorp.es/get/pages/thorped/multipass?o=demo
```
Tokens:
Raw