# 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 %}