Documentation

Start Here

IntroductionCore ConceptsHow It Works1. Create Your App2. Add to Ring3. Test Gestures4. Send a Vibe

Apps

App TypesLifecycleDeveloper Info

Gestures

Receiving GesturesResponding

Vibes

PatternsTriggeringRing UIUse Cases

Webhooks

Event TypesPayload StructureVerificationLocal Dev

Connect

How It WorksIdentifiersSetupToken ExchangeSecurity

Submissions

Before SubmittingHow to SubmitReview CriteriaAfter Approval

API Reference

Authentication/apps/vibes/installs/users

Recipes

Claude AI Agent SkillSetup PromptCLAUDE.md SetupExamples

Apps

Apps are the core building blocks of your ARKH integration. Each app defines how gestures are handled and where events are delivered.

When creating an app, you'll provide:

  • name - A display name for your app
  • app_type - One of "control", "device", or "preferred_notification"
  • description - A description of your app
  • webhook_url - (optional) The URL where gesture events will be sent. Required for gestures, not needed for vibes.
  • category - (optional) App category for discovery
  • special_instructions - (optional) Additional instructions for your app

App Types

Type

Description

control

Apps that live alongside other widgets. Perfect for media players, smart home remotes, gaming, or presentations. Users can switch between multiple control apps.

device

Apps that take full control of the ring as a dedicated input device—ideal for VR headsets, AR glasses, or drones. When active, no other controls receive gestures.

preferred_notification

Apps that send targeted notifications to the ring. Users pin your app to a priority slot (P1–P3) in their Vibes view. Supports optional confirm/reject/dismiss or emoji responses via response_config. See the Webhooks documentation for the response flow.

Each app type has its own lifecycle events. Control apps receive control.passive when the ring enters passive mode. Preferred Notification apps receive notification.responded when a user answers a vibe. See the Webhooks documentation for the complete event lifecycle.

App Development Lifecycle

Every app goes through a lifecycle from creation to public release. You can test privately before submitting for review.

1

Draft

Your app is being configured. Implement gesture handlers and vibe triggers into your app. Not usable yet.

2

Private

Publish your app to start testing in your personal account connected to your ring. Only you can see it.

3

In Review

Ready to go public? Submit for review. ARKH checks for security, quality, and guideline compliance.

4

Public

Approved and live. Your app is now visible to all users in the widget manager.

Suspended

App has been disabled by ARKH, usually for policy violations or security concerns. You'll be contacted with next steps.

Developer Info

Your Developer Info is displayed to users when they view your app in the widget manager. This information helps users trust your app and know how to contact you for support.

  • Display Name - Your name or brand (e.g., "Acme Labs")
  • Developer Logo - 80×80px PNG or JPG, shown in app listings
  • Support Email - Public contact for user support
  • Website URL - Link to your website or app page
  • Review Email - Private contact for ARKH during app review

Developer Info applies to all your apps. Configure it once in the Developer Info section of any app, and it will appear on all your published apps.

See the /apps API for programmatic app management.