Skip to main content

Register Endpoints (HCS-21)

Use this flow when you want to publish an adapter or endpoint declaration to the broker's HCS-21 adapter registry. This is separate from agent UAID registration with registerAgent(...).

Choose the right registration flowDirect link to Choose the right registration flow​

GoalAPI surfaceSDK methods
Publish a discoverable agent UAID/register, /register/quote, /register/progress/{attemptId}registerAgent, getRegistrationQuote, waitForRegistrationCompletion
Publish an adapter or endpoint declaration/adapters/registry/categories, /adapters/registry/adapters, /adapters/registry/submissions/{submissionId}adapterRegistryCategories, createAdapterRegistryCategory, submitAdapterRegistryAdapter, adapterRegistrySubmissionStatus

What the broker expectsDirect link to What the broker expects​

The OpenAPI request schema for POST /api/v1/adapters/registry/adapters requires:

  • adapterId
  • adapterName
  • entity
  • package
  • config
  • manifest

Optional fields include stateModel, signature, manifestPointer, manifestSequence, keywords, categorySlug, and newCategory.

The broker accepts the submission asynchronously and returns 202 Accepted with a submissionId. Poll the submission status endpoint until the broker reports completed or failed.

Step 1 - Inspect categories and existing entriesDirect link to Step 1 - Inspect categories and existing entries​

Use the read endpoints first so you can reuse an existing category slug when one already fits your adapter.

const categories = await client.adapterRegistryCategories();
const existing = await client.adapterRegistryAdapters({
  query: 'customer support',
  limit: 5,
});

console.log(categories.categories.map(category => category.slug));
console.log(existing.adapters.map(adapter => adapter.adapterId));

Step 2 - Create a category when neededDirect link to Step 2 - Create a category when needed​

If no existing category fits, create one explicitly or pass the same payload as newCategory during submission.

const category = await client.createAdapterRegistryCategory({
  name: 'Customer Support',
  slug: 'customer-support',
  description: 'Adapters that expose customer support endpoints and routing metadata.',
  type: 'custom',
  metadata: {
    version: '1.0.0',
    operator: {
      account: '0.0.12345',
      name: 'Example Labs',
      contact: 'hello@example.com',
    },
    entityTypes: ['agent-endpoint'],
    tags: ['support', 'a2a'],
  },
});

console.log(category.slug, category.topicId);

Step 3 - Submit the endpoint declarationDirect link to Step 3 - Submit the endpoint declaration​

The HCS-21 manifest describes the adapter package, runtime, and capabilities. The submission payload wraps that manifest together with the broker-facing config block and category selection.

import type {
  AdapterManifest,
  SubmitAdapterRegistryAdapterRequest,
} from '@hashgraphonline/standards-sdk';

const manifest: AdapterManifest = {
  meta: {
    spec_version: '1.0.0',
    adapter_version: '1.0.0',
    generated: new Date().toISOString(),
  },
  adapter: {
    name: 'Customer Support HTTP Adapter',
    id: 'customer-support-http',
    maintainers: [{ name: 'Example Labs', contact: 'hello@example.com' }],
    license: 'Apache-2.0',
  },
  package: {
    registry: 'npm',
    artifacts: [
      {
        url: 'https://registry.npmjs.org/@example/customer-support-http/-/customer-support-http-1.0.0.tgz',
        digest: 'sha384-REPLACE_WITH_REAL_DIGEST',
      },
    ],
  },
  runtime: {
    platforms: ['nodejs'],
    primary: 'nodejs',
    entry: 'dist/index.js',
  },
  capabilities: {
    discovery: true,
    communication: true,
    protocols: ['a2a'],
    discovery_tags: ['support', 'routing'],
    communication_channels: ['https'],
  },
  consensus: {
    required_fields: ['adapter.id', 'runtime.entry'],
    hashing: 'sha384',
  },
};

const payload: SubmitAdapterRegistryAdapterRequest = {
  adapterId: 'customer-support-http',
  adapterName: 'Customer Support HTTP Adapter',
  entity: 'agent-endpoint',
  package: {
    registry: 'npm',
    name: '@example/customer-support-http',
    version: '1.0.0',
    integrity: 'sha512-REPLACE_WITH_REAL_INTEGRITY',
  },
  config: {
    type: 'http',
    endpoint: 'https://agent.example.com/a2a',
    account: '0.0.12345',
  },
  manifest,
  keywords: ['support', 'a2a', 'customer-service'],
  categorySlug: 'customer-support',
};

const submission = await client.submitAdapterRegistryAdapter(payload);
console.log(submission.submissionId, submission.status);

Step 4 - Poll submission statusDirect link to Step 4 - Poll submission status​

The submission status response wraps the current record in a submission object. Watch the status field until it leaves pending or running.

let current = await client.adapterRegistrySubmissionStatus(submission.submissionId);

while (
  current.submission.status === 'pending' ||
  current.submission.status === 'running'
) {
  await new Promise(resolve => setTimeout(resolve, 2000));
  current = await client.adapterRegistrySubmissionStatus(submission.submissionId);
}

if (current.submission.status !== 'completed') {
  throw new Error(current.submission.error ?? 'Endpoint registration failed');
}

console.log(current.submission.resultPayload);

Next stepsDirect link to Next steps​

  • Use adapterRegistryAdapters(...) to confirm the published entry can be queried by category, entity, keywords, or free-text query.
  • Keep communicationProtocol and agent UAID registration separate from this HCS-21 flow. If you also need a discoverable agent UAID, continue with First Agent Registration.
  • For the method-by-method reference, see Registry Broker Client API.