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 home.arke.institute, create a collection, and upload some materials through the UI.

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 home.arke.institute and open the AI chat. Ask it to generate an API key for you. You'll receive a key that starts with uk_ (user key). Copy it somewhere safe -- you'll need it for every API call.

Treat your API key like a password. Don't commit it to source control or share it publicly.

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,
});

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:

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

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://arke-v1.arke.institute/collections \
  -H "Authorization: ApiKey $ARKE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "My Research",
    "description": "A collection for testing the Arke API"
  }'

SDK

const { data: collection, error } = await arke.api.POST('/collections', {
  body: {
    label: 'My Research',
    description: 'A collection for testing the Arke API',
  },
});

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

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

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 document entity inside your collection:

cURL

curl -X POST https://arke-v1.arke.institute/entities \
  -H "Authorization: ApiKey $ARKE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "document",
    "collection": "COLLECTION_ID",
    "properties": {
      "label": "Q1 Planning Notes",
      "description": "Notes from the Q1 planning meeting covering roadmap priorities, resource allocation, and key milestones for the quarter."
    }
  }'

SDK

const { data: entity, error } = await arke.api.POST('/entities', {
  body: {
    type: 'document',
    collection: 'COLLECTION_ID',
    properties: {
      label: 'Q1 Planning Notes',
      description:
        'Notes from the Q1 planning meeting covering roadmap priorities, resource allocation, and key milestones for the quarter.',
    },
  },
});

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 01JXXXXXXXXXXXXXXXXXXXXXXXXX)
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://arke-v1.arke.institute/search/entities \
  -H "Authorization: ApiKey $ARKE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "roadmap priorities",
    "collection_pi": "COLLECTION_ID",
    "limit": 5
  }'

SDK

const { data: results, error } = await arke.api.POST('/search/entities', {
  body: {
    query: 'roadmap priorities',
    collection_pi: 'COLLECTION_ID',
    limit: 5,
  },
});

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

Your entity should appear in the results even though the query ("roadmap priorities") doesn't exactly match the entity text. That's semantic search -- it understands that "roadmap priorities" is conceptually related to "roadmap priorities, resource allocation, and key milestones."

The response includes a score for each result indicating semantic similarity.

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://arke-v1.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
200 OK -- returns the Arweave transaction ID

Once you have the transaction ID, your entity's full manifest 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

On this page