Arke

Quickstart

Get started with the Arke API—create a collection, add an entity, search for it, and verify its attestation.

Not a developer? You can try Arke without writing any code. Create an account at arke.institute, create a collection, and upload your files!

This guide walks you through the core Arke workflow: authenticate, create a collection, add an entity with text content, search for it semantically, and verify its permanent attestation on Arweave.

1. Get your API key

Sign in at arke.institute. Once authenticated through the web interface.

Open the AI chat at arke.institute and ask it to generate an API key for you.

Treat your API key like a password. Don't commit it to source control or share it publicly. Keys expire after 90 days by default.

Set it as an environment variable so the examples below just work:

export ARKE_TOKEN="uk_your_key_here"

2. Choose your client

You can call the Arke API directly with cURL, or use the TypeScript SDK. Both are shown side by side throughout this guide.

TypeScript SDK

npm install @arke-institute/sdk
import { ArkeClient } from '@arke-institute/sdk';

const arke = new ArkeClient({
  authToken: process.env.ARKE_TOKEN,
});

// Verify authentication
const { data: me } = await arke.api.GET('/users/me');
console.log('Authenticated as:', me.properties.label);

The SDK auto-detects whether your token is a JWT or API key and sets the correct Authorization header (Bearer or ApiKey).

cURL

All cURL examples use the $ARKE_TOKEN environment variable from step 1. Verify your key works by fetching your user profile:

curl https://api.arke.institute/users/me \
  -H "Authorization: ApiKey $ARKE_TOKEN"

This returns your user entity with your ID, label, and profile data:

{
  "id": "01JUSER123456789ABCDEFGH",
  "type": "user",
  "ver": 1,
  "cid": "bafyrei...",
  "properties": {
    "label": "Your Name",
    "email": "you@example.com"
  }
}

3. Create a collection

Collections are the fundamental organizing unit in Arke. They define permission boundaries—who can view, edit, or manage the entities inside.

cURL

curl -X POST https://api.arke.institute/collections \
  -H "Authorization: ApiKey $ARKE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "The Pequod'\''s Voyage",
    "description": "A collection documenting Captain Ahab'\''s obsessive pursuit of the white whale"
  }'

SDK

const { data: collection, error } = await arke.api.POST('/collections', {
  body: {
    label: "The Pequod's Voyage",
    description: "A collection documenting Captain Ahab's obsessive pursuit of the white whale",
  },
});

console.log('Collection ID:', collection.id);

The response includes the new collection's metadata:

{
  "id": "01KFNR0H0Q791Y1SMZWEQ09FGV",
  "type": "collection",
  "ver": 1,
  "cid": "bafyrei...",
  "created_at": "2026-01-28T12:00:00.000Z",
  "properties": {
    "label": "The Pequod's Voyage",
    "description": "A collection documenting Captain Ahab's obsessive pursuit of the white whale"
  }
}

Save the returned id—you'll use it in the next steps. You are automatically the owner of any collection you create.

Under the hood: Collections are entities with type: "collection". The /collections endpoint is a convenience wrapper around /entities with collection-specific defaults. You can also create collections via POST /entities with type: "collection".

4. Add an entity

Entities are the core data objects on the Arke network. Every entity has a type, a set of properties, and belongs to one or more collections.

Create a file entity inside your collection:

cURL

curl -X POST https://api.arke.institute/entities \
  -H "Authorization: ApiKey $ARKE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "file",
    "collection": "COLLECTION_ID",
    "properties": {
      "label": "Chapter 1. Loomings",
      "description": "Call me Ishmael. Some years ago—never mind how long precisely—having little or no money in my purse, and nothing particular to interest me on shore, I thought I would sail about a little and see the watery part of the world."
    }
  }'

SDK

const { data: entity, error } = await arke.api.POST('/entities', {
  body: {
    type: 'file',
    collection: 'COLLECTION_ID',
    properties: {
      label: 'Chapter 1. Loomings',
      description:
        'Call me Ishmael. Some years ago—never mind how long precisely—having little or no money in my purse, and nothing particular to interest me on shore, I thought I would sail about a little and see the watery part of the world.',
    },
  },
});

console.log('Entity ID:', entity.id);
console.log('CID:', entity.cid);

Replace COLLECTION_ID with the ID from step 3.

Every entity gets:

  • A unique ID (a 26-character ULID like 01JXXXXXXXXXXXXXXXXXXXXXXX)
  • A content-addressed CID—a hash of the entity's manifest
  • A version number starting at 1

5. Search for your entity

Arke indexes entity properties for semantic search—meaning you can search by meaning, not just keywords. The indexer runs asynchronously, so wait a few seconds after creating your entity before searching.

cURL

curl -X POST https://api.arke.institute/search/entities \
  -H "Authorization: ApiKey $ARKE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "why did Ishmael go to sea",
    "collection_pi": "COLLECTION_ID",
    "limit": 5
  }'

SDK

const { data: results, error } = await arke.api.POST('/search/entities', {
  body: {
    query: 'why did Ishmael go to sea',
    collection_pi: 'COLLECTION_ID',
    limit: 5,
  },
});

for (const result of results.results) {
  console.log(`${result.label} (score: ${result.score})`);
}

The response includes ranked results with similarity scores:

{
  "results": [
    {
      "pi": "01KFNR849AZNBWE9DYJRZR7PSA",
      "type": "file",
      "label": "Chapter 1. Loomings",
      "score": 0.87,
      "collection_pi": "01KFNR0H0Q791Y1SMZWEQ09FGV"
    }
  ],
  "metadata": {
    "query": "why did Ishmael go to sea",
    "collections_searched": 1,
    "result_count": 1
  }
}

Your entity should appear in the results even though the query ("why did Ishmael go to sea") doesn't exactly match the entity text. That's semantic search—it understands that the question is conceptually related to "having little or no money in my purse... I thought I would sail about."

6. Verify the Arweave attestation

Every entity on Arke is permanently attested on Arweave, a decentralized permanent storage network. The full entity manifest is uploaded -- not just a hash—so the data can be independently verified and reconstructed by anyone.

Attestation happens asynchronously. Wait up to 10 minutes after creating your entity, then check:

cURL

curl https://api.arke.institute/entities/ENTITY_ID/attestation \
  -H "Authorization: ApiKey $ARKE_TOKEN"

SDK

const { data, response } = await arke.api.GET(
  '/entities/{id}/attestation',
  {
    params: { path: { id: 'ENTITY_ID' } },
  }
);

if (response.status === 202) {
  console.log('Attestation is still being processed. Try again shortly.');
} else {
  console.log('Arweave TX:', data.tx_id);
}
  • 202 Accepted—the attestation is queued but not yet uploaded:
{
  "pi": "01KFNR81RMVAX2BBMMBW51V97D",
  "ver": 1,
  "cid": "bafyrei...",
  "attestation_status": "pending",
  "message": "Attestation upload in progress"
}
  • 200 OK—the attestation is complete:
{
  "pi": "01KFNR81RMVAX2BBMMBW51V97D",
  "ver": 1,
  "cid": "bafyrei...",
  "arweave_tx": "5l8y5oKhy3pDvTjGY7rHKl76AC-kVh-C1NpszRx-_14",
  "arweave_url": "https://arweave.net/5l8y5oKhy3pDvTjGY7rHKl76AC-kVh-C1NpszRx-_14",
  "ts": 1769183133772
}

Once you have the transaction ID, you can view the full manifest directly at arweave_url. Your entity's data is permanently stored on Arweave—it cannot be altered or deleted. This provides a verifiable proof that the content existed at that point in time.

Next steps

Now that you've created a collection, added an entity, searched for it, and verified its attestation, here's where to go deeper:

  • Files—Upload PDFs, images, and documents that are automatically processed (OCR, chunking, descriptions) and become searchable
  • Relationships—Link entities together to build knowledge graphs
  • Collections—Manage roles and grant permission to collaborators (owner, editor, viewer)
  • Search & Query—Advanced semantic search, graph traversal, and the Argo query language
  • Attestation—Learn more about permanent verification on Arweave
  • SDK Reference—Full SDK documentation

Introduction

Arke is a public knowledge network for storing, discovering, and connecting information.

Key Concepts

Core concepts in Arke—entities, content-addressed versioning, relationships, collections, and permissions.

On this page

1. Get your API key2. Choose your clientTypeScript SDKcURL3. Create a collectioncURLSDK4. Add an entitycURLSDK5. Search for your entitycURLSDK6. Verify the Arweave attestationcURLSDKNext steps