# Search Inscriptions

{% hint style="success" %}
As of January 2024, access to search endpoints are restricted to API Keys and allowlisted domains, if you need access to these endpoints please reach out to us on [discord](https://discord.ordinalsbot.com).

All results are as ***sorted earliest first by inscription numbers***, so they can be used to check which inscription is first for a certain hash.
{% endhint %}

### Search all inscriptions for any text value

## Text Search

<mark style="color:blue;">`GET`</mark> `https://api.ordinalsbot.com/search`

You can search for any text string against all existing inscriptions.

Pagination options can be specified by adding `itemsPerPage` and `page`\
values in the query parameters. Response provides an array of results as well as information on current page, total page numbers and total items available for the search criteria.\
\
Response structure:

`{` \
&#x20;         `results: [{},{},{},{}], // array of restults` \
&#x20;         `count: 0, // number of Ordinals in the current results array`\
&#x20;         `currentPage: page, // current page number` \
&#x20;         `totalPages: 0, // total pages that can be returned for the current search criteria` \
&#x20;         `totalItems: 0 // total items in the database for the current search criteria` \
`}`

#### Query Parameters

| Name                                   | Type   | Description                                                                                                                                                                                                                                                               |
| -------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| text<mark style="color:red;">\*</mark> | String | <p>The text you want to search</p><p></p><p><strong>Note</strong>: text field can also accept a list of comma separated strings such that it will do a search where ALL of these strings exist in the inscription content.</p><p><code>?text=some,random,words</code></p> |
| page                                   | Number | The page number in the list of pages to return by default the first page is returned                                                                                                                                                                                      |
| itemsPerPage                           | Number | The number of iterms to return in each page, this defaults to 100                                                                                                                                                                                                         |

#### Headers

| Name      | Type   | Description                                                  |
| --------- | ------ | ------------------------------------------------------------ |
| x-api-key | String | <p>API Key</p><p>Required if domain is not on allowlist.</p> |

{% tabs %}
{% tab title="200: OK Normal Response" %}

```json
{
    "status":"ok",
    "count": 1,
    "currentPage": 3,
    "totalPages": 3,
    "totalItems": 102
    "itemsPerPage": 100,
    "results":
   [
      {
         "txid":"87a1d452d2dcc89c66018a897c9910629d6c3173820979a740730e195433fd26",
         "inputindex":"0",
         "inscriptionid":"87a1d452d2dcc89c66018a897c9910629d6c3173820979a740730e195433fd26i0",
         "inscriptionnumber":"181258",
         "blockheight":"778281",
         "contentstr":"{\"p\":\"sns\",\"op\":\"reg\",\"name\":\"ordinalsbot.sats\"}",
         "contenttypestr":"text/plain;charset=utf-8",
         "contenthash":"c987a51dc14fb8e9e909b8482c1c62df246904442e851f41d6891e7af3042b23",
         "contentlength":"30",
         "metadatastr": "{\"integer\":123,\"float\":123.456,\"string\":\"hello world\",\"array\":[1,2,3],\"object\":{\"key1\":\"value1\",\"key2\":\"value2\"},\"boolean\":true,\"null\":null,\"undefined\":\"undefined\",\"byteString\":\"48656c6c6f20576f726c64\",\"taggedData\":{\"tag\":1,\"value\":\"2022-12-31T23:59:59Z\"}}",
         "createdat":"2023-03-08T21:05:16.349Z"
      }
   ]
}
```

{% endtab %}

{% tab title="200: OK Response with Error" %}

```
{
    status: 'error', 
    error: 'error reason'
}
```

{% endtab %}

{% tab title="500: Internal Server Error Server side error" %}

```
{
    status: 'error',
    reason: 'server error'
}
```

{% endtab %}
{% endtabs %}

### Search for an existing Image or File

Use this endpoint to check if a certain image was inscribed before. We call this a "hash check".

{% hint style="info" %}
Image Search is done by hashing the image file and checking against previous inscriptions' hashes.

To use this endpoint you need to sha256 hash the image file content as below:
{% endhint %}

```javascript
const base64encodedimage = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAoElEQVR42u2VMQ6AMAhFe0fT1d3V3cv0ojUxaoBSBEo3Sf7S6n+UIqb0R2BUoHjjnPOrSBAyphqFiOajEJW5F9KrdyMvBL10lK0r+qwJ8GVOIVoAm/26L5eg8bNmPQWbfb1rzq3B+3ADaPZwzQJoukZ7B1qICkD3wgHTTzAVwO1ZOwlBep3DQc1tqimR1Vz8FqSB55qmEmD0fyACmBEuxglnHBu4i1egeQAAAABJRU5ErkJggg=='
const buff = Buffer.from(base64encodedimage.split(";base64,")[1], 'base64');
const imageHash = bitcoin.crypto.sha256(buff).toString('hex')
```

## Search for Image

<mark style="color:blue;">`GET`</mark> `https://api.ordinalsbot.com/search`

Check for previous occurrences of an image in inscriptions. Results array will be sorted by ascending block height.\
\
Pagination parameters are the same as text search

#### Query Parameters

<table><thead><tr><th width="106">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>hash<mark style="color:red;">*</mark></td><td>String</td><td>sha256 hash of an image buffer in hex</td></tr><tr><td>page</td><td>Number</td><td>The page number in the list of pages to return by default the first page is returned</td></tr><tr><td>itemsPerPage</td><td>Number</td><td>The number of iterms to return in each page, this defaults to 100</td></tr></tbody></table>

#### Headers

| Name      | Type   | Description                                                  |
| --------- | ------ | ------------------------------------------------------------ |
| x-api-key | String | <p>API Key</p><p>Required if domain is not on allowlist.</p> |

{% tabs %}
{% tab title="200: OK Normal Response" %}

```json
{
    "status":"ok",
    "count": 1,
    "currentPage": 3,
    "totalPages": 3,
    "totalItems": 102
    "itemsPerPage": 100,
    "results":
    [
        {
            "txid":"ea0d...a8",
            "inputindex":"0",
            "inscriptionid":"ea0d....8i0",
            "blockheight":"775528",  // use blockheight as timestamp
            "contenttypestr":"image/png",
            "contenthash":"59edca9...a9ca4c80d",
            "contentlength":"217",
            "createdat":"2023-03-08T16:30:38.690Z" // this is when record is parsed - not the block timestamp
        },
        ...
    ]
}
```

{% endtab %}

{% tab title="200: OK Error Response with Cause" %}

```
{
    status: 'error', 
    error: 'error reason'
}
```

{% endtab %}

{% tab title="500: Internal Server Error Server side error" %}

```
{
    status: 'error',
    reason: 'server error'
}
```

{% endtab %}
{% endtabs %}

### Search all inscriptions for any metadata value

## Metadata Search

<mark style="color:blue;">`GET`</mark> `https://api.ordinalsbot.com/indexer/metadata`

You can search for any text inside metadata fields of all existing inscriptions.

Pagination options can be specified by adding `itemsPerPage` and `page`\
values in the query parameters. Response provides an array of results as well as information on current page, total page numbers and total items available for the search criteria.\
\
Response structure:

`{` \
&#x20;         `results: [{},{},{},{}], // array of restults` \
&#x20;         `count: 0, // number of Ordinals in the current results array`\
&#x20;         `currentPage: page, // current page number` \
&#x20;         `totalPages: 0, // total pages that can be returned for the current search criteria` \
&#x20;         `totalItems: 0 // total items in the database for the current search criteria` \
`}`

#### Query Parameters

| Name                                   | Type   | Description                                                                                                                                                                                                                                                                          |
| -------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| text<mark style="color:red;">\*</mark> | String | <p>The text you want to search inside <strong>metadata</strong> fields of all inscriptions. </p><p></p><p>This can be a list of strings separated by comma if you want to search for multiple strings at once (<strong>AND</strong> search) i.e.:</p><p>?text=donot,trust,verify</p> |
| page                                   | Number | The page number in the list of pages to return by default the first page is returned                                                                                                                                                                                                 |
| itemsPerPage                           | Number | The number of iterms to return in each page, this defaults to 100                                                                                                                                                                                                                    |

#### Headers

| Name      | Type   | Description                                                  |
| --------- | ------ | ------------------------------------------------------------ |
| x-api-key | String | <p>API Key</p><p>Required if domain is not on allowlist.</p> |

{% tabs %}
{% tab title="200: OK Normal Response" %}

```json
{
    "status":"ok",
    "count": 1,
    "currentPage": 3,
    "totalPages": 3,
    "totalItems": 102
    "itemsPerPage": 100,
    "results":
   [
      {
         "txid":"87a1d452d2dcc89c66018a897c9910629d6c3173820979a740730e195433fd26",
         "inputindex":"0",
         "inscriptionid":"87a1d452d2dcc89c66018a897c9910629d6c3173820979a740730e195433fd26i0",
         "inscriptionnumber":"181258",
         "blockheight":"778281",
         "contentstr":"{\"p\":\"sns\",\"op\":\"reg\",\"name\":\"ordinalsbot.sats\"}",
         "contenttypestr":"text/plain;charset=utf-8",
         "contenthash":"c987a51dc14fb8e9e909b8482c1c62df246904442e851f41d6891e7af3042b23",
         "contentlength":"30",
         "metadatastr": "{\"integer\":123,\"float\":123.456,\"string\":\"hello world\",\"array\":[1,2,3],\"object\":{\"key1\":\"value1\",\"key2\":\"value2\"},\"boolean\":true,\"null\":null,\"undefined\":\"undefined\",\"byteString\":\"48656c6c6f20576f726c64\",\"taggedData\":{\"tag\":1,\"value\":\"2022-12-31T23:59:59Z\"}}",
         "createdat":"2023-03-08T21:05:16.349Z"
      }
   ]
}
```

{% endtab %}

{% tab title="200: OK Response with Error" %}

```
{
    status: 'error', 
    error: 'error reason'
}
```

{% endtab %}

{% tab title="500: Internal Server Error Server side error" %}

```
{
    status: 'error',
    reason: 'server error'
}
```

{% endtab %}
{% endtabs %}

## Search for Inscription ID

<mark style="color:blue;">`GET`</mark> `https://api.ordinalsbot.com/indexer/inscription`

Check for an inscription in our indexer. This endpoint allows you to see if an inscription is indexed by our indexer and will return content hash and content string.

#### Query Parameters

<table><thead><tr><th width="106">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>id<mark style="color:red;">*</mark></td><td>String</td><td>Inscription id i.e. <code>98e0f396ecff2eef7914e35a90a44e3bb7601c7071985cfacfd2d5f29c5207e7i0</code></td></tr></tbody></table>

#### Headers

| Name      | Type   | Description                                                  |
| --------- | ------ | ------------------------------------------------------------ |
| x-api-key | String | <p>API Key</p><p>Required if domain is not on allowlist.</p> |

{% tabs %}
{% tab title="200: OK Normal Response" %}

```json
{
    "status": "ok",
    "results": [
        {
            "txid": "98e0f396ecff2eef7914e35a90a44e3bb7601c7071985cfacfd2d5f29c5207e7",
            "inputindex": "0",
            "inscriptionid": "98e0f396ecff2eef7914e35a90a44e3bb7601c7071985cfacfd2d5f29c5207e7i0",
            "inscriptionnumber": "45652",
            "blockheight": "222945",
            "contenttypestr": "video/mp4",
            "owner": null,
            "content": "000000206674797069736f6d0000020069736f6d69736f32617663316d703431000000086672656500000a756d646174000002ae0605ffffaadc45e9bde6d948b7962cd820d923eeef78323634202d20636f7265203136342072333130382033316531396639202d20482e3236342f4d5045472d342041564320636f646563202d20436f70796c65667420323030332d32303233202d20687474703a2f2f7777772e766964656f6c616e2e6f72672f783236342e68746d6c202d206f7074696f6e733a2063616261633d31207265663d33206465626c6f636b3d313a303a3020616e616c7973653d3078333a3078313133206d653d686578207375626d653d37207073793d31207073795f72643d312e30303a302e3030206d697865645f7265663d31206d655f72616e67653d3136206368726f6d615f6d653d31207472656c6c69733d31203878386463743d312063716d3d3020646561647a6f6e653d32312c313120666173745f70736b69703d31206368726f6d615f71705f6f66667365743d2d3220746872656164733d34206c6f6f6b61686561645f746872656164733d3120736c696365645f746872656164733d30206e723d3020646563696d6174653d3120696e7465726c616365643d3020626c757261795f636f6d7061743d3020636f6e73747261696e65645f696e7472613d3020626672616d65733d3320625f707972616d69643d3220625f61646170743d3120625f626961733d30206469726563743d3120776569676874623d31206f70656e5f676f703d3020776569676874703d32206b6579696e743d323530206b6579696e745f6d696e3d3235207363656e656375743d343020696e7472615f726566726573683d302072635f6c6f6f6b61686561643d34302072633d637266206d62747265653d31206372663d32332e302071636f6d703d302e36302071706d696e3d302071706d61783d3639207170737465703d342069705f726174696f3d312e34302061713d313a312e30300080000002ab658884003bfffef74ebf029b45976a0392570af6caa42659fdd28e1d9e92a8270e6d6aa52ce3d7a7b04aa00b6ca6d7c4f54315dcd164242960764aafcbb4cf97b20af1ad3ead8dcd324c4de45ceb06e413cf3c164dc1daeac2e391af678e58f356bccaf8bfe8280c04a65bff52bc3b29eeb7cb3a7608263f7fcf7279e79b29637d8583f62d4e42a791ed8b548ec2e1557ec559e331565a1712da253fb44e77fa99939ac26ed85a6bc9c43edc44e70ea395ac81d2a27e108ea4333146d2c4303202f3f700a70fbbf9fc9b2e7fa9571d307fe3f959ac8bf1f6da68ea7c5c1d1b57b456af389bbea3708deb9508ea98a0d47430df81dd035cd2d49a646450bb2c18f05cc97747763874faf95c0e22ce353b1211a126a1cdace2b3857578e54958a598b656a855485d2756a95bd2b866b4bae2c0697bb8651d0e295a12beba927da9b39d099d6319669a84c1e9e4bd5cc29785b429f13153d1cd778e86f0175fc96d43d40bea19343bf9629a487f22f62e949283bca903809ee912a1b34ef3191dd1365f81d46a8898d83fd90191d820c0beb550617d24dee16bcc3f96b1afdf059e72a84ff1f745e121d294610f4241af5a1c4b4b6280e119c0bb2aabc0c5eca9e037bd55274bf196344c4bc52ee57daa3aba56cfcb51c6af8f07bc48a506e451dcc3fe66a6d0dc495aed3c98aaae1f08ff2167e284bd45f96c6e2629599a8eddf6f96f3ea7bf896a4997f692c033e34479d7b480f8c5ac1df57cb8e322c43f6349c9e0adfbdd7e4e199309cae86fd5845b362d9be8549066e3cef64e0ec9eb13e9946f56b497d8752c457088b8939cc2eb3dcd25c31f62088e14ea32663d815ea1c4628f35a918ae2998eabeb2dec22ec33f1286cf5305b7e554d53afb4a2edf21a1f34c820a44f77ae49daf71f1bf42b61dbde8fa73688e13b389040ed1bf6fe978dd096f218120fa06aa7700000011419a246c43bffea996085f105a5dd90e38000000c1419e4278857fd55ff9141fffc7f55189ce22c8a1caf384806e209d74d9c176c6a5a29aef5d3f2bcc83b2d40093725db545277faf66bfd0206d86e5f82884fb3d2dd0eff79eee0be90ec51854bf2baee2c5c80094af36e5cd006dfd97de760bb5843f9a424c5ce6e4737c59f6b1c15deb6f31d5652cd0e65486f54cbacb5e390e07873e96aeca2d3bce44dc4d08734ffb5934aa43c27edf02c09547e55bcfc9e083d947ca2fc694d744e8c01ce265e180bc4ecec7ea72f672de9ff4584b534aeb3b00000010019e6174427ff75f20c0653681ea8cf000000021019e636a427ff5f690916542f15dc8dafb0d7b38b0f35db5ac4726a711d55a285d00000012419a6849a84168994c0877fffea99600c48100000024419e8645112c2bfff64427732d9057f588a36bfc7ef8ca25c45db97faf353dfd151cd6290000000d019ea574427ff75f20bde7f57d0000000b019ea76a427ff5f690588400000012419aac49a8416c994c0877fffea99600c4800000000e419eca45152c2bfff64427692d810000000d019ee974427ff75f20bde7f57d0000000b019eeb6a427ff5f690588400000012419af049a8416c994c0877fffea99600c4810000000e419f0e45152c2bfff64427692d810000000d019f2d74427ff75f20bde7f57d0000000b019f2f6a427ff5f690588400000012419b3449a8416c994c0877fffea99600c4800000000e419f5245152c2bfff64427692d810000000d019f7174427ff75f20bde7f57d0000000b019f736a427ff5f690588400000012419b7849a8416c994c0877fffea99600c4810000000e419f9645152c2bfff64427692d800000000d019fb574427ff75f20bde7f57d0000000b019fb76a427ff5f690588500000012419bbc49a8416c994c0877fffea99600c4800000000e419fda45152c2bfff64427692d810000000d019ff974427ff75f20bde7f57d0000000b019ffb6a427ff5f690588500000012419be049a8416c994c0877fffea99600c4810000000e419e1e45152c2bfff64427692d800000000d019e3d74427ff75f20bde7f57d0000000b019e3f6a427ff5f690588500000012419a2449a8416c994c0877fffea99600c4800000000e419e4245152c2bfff64427692d810000000d019e6174427ff75f20bde7f57d0000000b019e636a427ff5f690588500000011419a6849a8416c994c086ffffea78401830000000e419e8645152c2bfff64427692d810000000d019ea574427ff75f20bde7f57d0000000b019ea76a427ff5f690588400000011419aac49a8416c994c086ffffea78401830000000e419eca45152c2bfff64427692d810000000d019ee974427ff75f20bde7f57d0000000b019eeb6a427ff5f690588400000011419af049a8416c994c086ffffea78401830000000e419f0e45152c2bfff64427692d810000000d019f2d74427ff75f20bde7f57d0000000b019f2f6a427ff5f690588400000011419b3449a8416c994c086ffffea78401830000000e419f5245152c2bfff64427692d810000000d019f7174427ff75f20bde7f57d0000000b019f736a427ff5f690588400000011419b7849a8416c994c085ffffe8cb005ed0000000e419f9645152c2bfff64427692d800000000d019fb574427ff75f20bde7f57d0000000b019fb76a427ff5f690588500000017419bbb4ba842105b208c06f1101bc80213fffdf10037a000000010419fd945152c27fff5f6905ef0c731810000000d019ffa6a427ff34920bdd584e7000005f06d6f6f760000006c6d766864000000000000000000000000000003e8000007d000010000010000000000000000000000000100000000000000000000000000000001000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000020000051b7472616b0000005c746b68640000000300000000000000000000000100000000000007d000000000000000000000000000000000000100000000000000000000000000000001000000000000000000000000000040000000008000000080000000000024656474730000001c656c73740000000000000001000007d00000040000010000000004936d646961000000206d64686400000000000000000000000000003c000000780055c400000000002d68646c72000000000000000076696465000000000000000000000000566964656f48616e646c6572000000043e6d696e6600000014766d68640000000100000000000000000000002464696e660000001c6472656600000000000000010000000c75726c2000000001000003fe7374626c000000ae7374736400000000000000010000009e61766331000000000000000100000000000000000000000000000000008000800048000000480000000000000001144c61766336312e332e313030206c69627832363400000000000000000000000018ffff00000034617663430164000bffe100176764000bacd942046840000003004000000f03c50a658001000668ebe3cb22c0fdf8f800000000146274727400000000000029b4000029b4000000187374747300000000000000010000003c000002000000001473747373000000000000000100000001000001e863747473000000000000003b00000001000004000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a000000000100000400000000010000000000000001000002000000000100000a00000000010000040000000001000000000000000100000200000000010000080000000002000002000000001c737473630000000000000001000000010000003c00000001000001047374737a00000000000000000000003c0000056100000015000000c500000014000000250000001600000028000000110000000f0000001600000012000000110000000f0000001600000012000000110000000f0000001600000012000000110000000f0000001600000012000000110000000f0000001600000012000000110000000f0000001600000012000000110000000f0000001600000012000000110000000f0000001500000012000000110000000f0000001500000012000000110000000f0000001500000012000000110000000f0000001500000012000000110000000f0000001500000012000000110000000f0000001b0000001400000011000000147374636f0000000000000001000000300000006175647461000000596d657461000000000000002168646c7200000000000000006d6469726170706c0000000000000000000000002c696c737400000024a9746f6f0000001c6461746100000001000000004c61766636312e312e313030",
            "contentstr": "",
            "contenthash": "9de52e1e280173e07081ec095b675e4d7b8854b705bc195037b3574cdc016082",
            "contentlength": "4237",
            "createdat": "2024-11-21T05:39:39.230Z"
        }
    ]
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ordinalsbot.com/api/search-inscriptions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.