Urbit Developers
  • Hoon

    • Overview
    • Cheat Sheet
    • Irregular forms
    • Hoon Errors
    • Hoon Style Guide
    • Basic Types
    • Advanced Types
    • Auras
    • Arvo
    • Standard Library

      • 1a: Basic Arithmetic
      • 1b: Tree Addressing
      • 1c: Molds and Mold-Builders
      • 2a: Unit Logic
      • 2b: List Logic
      • 2c: Bit Arithmetic
      • 2d: Bit Logic
      • 2e: Insecure Hashing
      • 2f: Noun Ordering
      • 2g: Unsigned Powers
      • 2h: Set Logic
      • 2i: Map Logic
      • 2j: Jar and Jug Logic
      • 2k: Queue Logic
      • 2l: Container from Container
      • 2m: Container from Noun
      • 2n: Functional Hacks
      • 2o: Normalizing Containers
      • 2p: Serialization
      • 2q: Molds and Mold-Builders
      • 3a: Modular and Signed Ints
      • 3b: Floating Point
      • 3c: Urbit Time
      • 3d: SHA Hash Family
      • 3e: AES encryption (Removed)
      • 3f: Scrambling
      • 3g: Molds and Mold-Builders
      • 4a: Exotic Bases
      • 4b: Text Processing
      • 4c: Tank Printer
      • 4d: Parsing (Tracing)
      • 4e: Parsing (Combinators)
      • 4f: Parsing (Rule-Builders)
      • 4g: Parsing (Outside Caller)
      • 4h: Parsing (ASCII Glyphs)
      • 4i: Parsing (Useful Idioms)
      • 4j: Parsing (Bases and Base Digits)
      • 4k: Atom Printing
      • 4l: Atom Parsing
      • 4m: Formatting Functions
      • 4n: Virtualization
      • 4o: Molds
      • 5a: Compiler Utilities
      • 5b: Macro Expansion
      • 5c: Compiler Backend & Prettyprinter
      • 5d: Parser
      • 5e: Molds and mold builders
      • 5f: Profiling support
      • Runes

        • Constants (Atoms and Strings)
        • + lus · Arms
        • | bar · Cores
        • $ buc · Structures
        • % cen · Calls
        • : col · Cells
        • . dot · Nock
        • / fas · Imports
        • ^ ket · Casts
        • ; mic · Make
        • ~ sig · Hints
        • = tis · Subject
        • ? wut · Conditionals
        • ! zap · Wild
        • --, == Terminators
        • Limbs and wings

          • Limbs
          • Wings
          • Zuse

            • 2d(1-5): To JSON, Wains
            • 2d(6): From JSON
            • 2d(7): From JSON (unit)
            • 2e(2-3): Print & Parse JSON
            • 2m: Ordered Maps
          • Arvo

            • Overview
            • Ames

              • Overview
              • Cryptography
              • API Reference
              • Scry Reference
              • Data Types
              • Behn

                • Overview
                • API Reference
                • Scry Reference
                • Examples
                • Clay

                  • Overview
                  • Architecture
                  • Using Clay
                  • Data Types
                  • Scry Reference
                  • API Reference
                  • Examples
                  • Marks

                    • Overview
                    • Writing Marks
                    • Using Marks
                    • Examples
                  • Dill

                    • Overview
                    • API Reference
                    • Scry Reference
                    • Data Types
                    • Eyre

                      • Overview
                      • External API Reference
                      • Internal API Reference
                      • Scry Reference
                      • Data Types
                      • Guide
                      • Gall

                        • Overview
                        • API Reference
                        • Data Types
                        • Threads Reference
                        • Iris

                          • Overview
                          • API Reference
                          • Data Types
                          • Example
                          • Jael

                            • Overview
                            • API Reference
                            • Scry Reference
                            • Data Types
                            • Examples
                            • Khan

                              • Overview
                              • API Reference
                              • Data Types
                              • Example
                              • Threads

                                • Overview
                                • HTTP API
                                • Reference
                                • Gall

                                  • Start Thread
                                  • Take Result
                                  • Take Facts
                                  • Stop Thread
                                  • Poke Thread
                                  • Examples

                                    • Fetch JSON
                                    • Child Thread
                                    • Main-loop
                                    • Poke Agent
                                    • Scry
                                    • Take Fact
                                  • Concepts

                                    • Scries
                                    • Subscriptions
                                    • Tutorials

                                      • Move Trace
                                      • Reference

                                        • Cryptography
                                        • Filesystem Hierarchy
                                      • Nock

                                        • Nock Definition
                                        • Explanation
                                        • Example
                                        • Implementations
                                        • Vere

                                          • C Runtime System
                                          • Land of Nouns
                                          • API overview by prefix
                                          • C in Urbit
                                          • Writing Jets
                                          • Cryptography
                                          • Azimuth

                                            • Overview
                                            • Urbit HD Wallet
                                            • Azimuth Data Flow
                                            • Azimuth.eth
                                            • Ecliptic.eth
                                            • Advanced Azimuth Tools
                                            • Life and Rift
                                            • Layer 2

                                              • Layer 2 Overview
                                              • Layer 2 Actions
                                              • Transaction Format
                                              • Rollers
                                              • Roller HTTP RPC-API
                                              • Custom Roller Tutorial
                                            • Glossary

                                              • Agent
                                              • Ames
                                              • API
                                              • Aqua
                                              • Arm
                                              • Arvo
                                              • Atom
                                              • Aura
                                              • Aural ASCII
                                              • Azimuth
                                              • Battery
                                              • Behn
                                              • Bowl
                                              • Bridge
                                              • Bunt
                                              • Card
                                              • Case
                                              • Cask
                                              • Cell
                                              • Censures
                                              • Claims
                                              • Clay
                                              • Cold atom
                                              • Comet
                                              • Commit
                                              • Cons
                                              • Context
                                              • Cord
                                              • Core
                                              • Delegated Sending
                                              • Desk
                                              • Dill
                                              • Document Proposal
                                              • Dojo
                                              • Door
                                              • Double-boot
                                              • Dry Gate
                                              • Duct
                                              • Ecliptic
                                              • Entropy
                                              • Event Log
                                              • Eyre
                                              • Face
                                              • Fact
                                              • Foo Bar Baz
                                              • Galaxy
                                              • Gall
                                              • Garden
                                              • Gate
                                              • Generator
                                              • Gift
                                              • Glob
                                              • HD Wallet
                                              • Helm
                                              • Hood
                                              • Hoon
                                              • Invite Tree
                                              • Iris
                                              • Jael
                                              • Jet
                                              • Kelvin versioning
                                              • Kelvin versioning
                                              • Keyfile
                                              • Keywords
                                              • Khan
                                              • Kiln
                                              • Landscape
                                              • Leg
                                              • List
                                              • Loobean
                                              • Lull
                                              • Mark
                                              • Metals
                                              • Mold
                                              • Monad
                                              • Moon
                                              • Move
                                              • Nock
                                              • Noun
                                              • ~
                                              • OTA Updates
                                              • Path Prefix
                                              • Path
                                              • @p
                                              • Payload
                                              • Peek
                                              • pH
                                              • Pier
                                              • Pill
                                              • Planet
                                              • Poke
                                              • Proxies
                                              • Replay
                                              • Factory Reset
                                              • Roller
                                              • Naive rollups
                                              • Rune
                                              • Runtime
                                              • Sail
                                              • Sample
                                              • Scry
                                              • Senate
                                              • Ship
                                              • Slam
                                              • Spider
                                              • Sponsor
                                              • Star
                                              • String
                                              • Subject Oriented Programming
                                              • Subject
                                              • Subscription
                                              • Tape
                                              • Thread
                                              • Trap
                                              • Udon
                                              • Upgrade Proposal
                                              • Userspace
                                              • Vane
                                              • Vase
                                              • Vere
                                              • Voting
                                              • Warm atom
                                              • Wet Gate
                                              • Wing
                                              • Wire
                                              • Wrapper
                                              • ~zod
                                              • Zuse
                                              • Additional

                                                • Cryptography
                                                • Mips (Maps of Maps)
                                                • Software Distribution

                                                  • Overview
                                                  • Docket File
                                                  • Glob
                                                Urbit Developers
                                                • Hoon

                                                  • Overview
                                                  • Cheat Sheet
                                                  • Irregular forms
                                                  • Hoon Errors
                                                  • Hoon Style Guide
                                                  • Basic Types
                                                  • Advanced Types
                                                  • Auras
                                                  • Arvo
                                                  • Standard Library

                                                    • 1a: Basic Arithmetic
                                                    • 1b: Tree Addressing
                                                    • 1c: Molds and Mold-Builders
                                                    • 2a: Unit Logic
                                                    • 2b: List Logic
                                                    • 2c: Bit Arithmetic
                                                    • 2d: Bit Logic
                                                    • 2e: Insecure Hashing
                                                    • 2f: Noun Ordering
                                                    • 2g: Unsigned Powers
                                                    • 2h: Set Logic
                                                    • 2i: Map Logic
                                                    • 2j: Jar and Jug Logic
                                                    • 2k: Queue Logic
                                                    • 2l: Container from Container
                                                    • 2m: Container from Noun
                                                    • 2n: Functional Hacks
                                                    • 2o: Normalizing Containers
                                                    • 2p: Serialization
                                                    • 2q: Molds and Mold-Builders
                                                    • 3a: Modular and Signed Ints
                                                    • 3b: Floating Point
                                                    • 3c: Urbit Time
                                                    • 3d: SHA Hash Family
                                                    • 3e: AES encryption (Removed)
                                                    • 3f: Scrambling
                                                    • 3g: Molds and Mold-Builders
                                                    • 4a: Exotic Bases
                                                    • 4b: Text Processing
                                                    • 4c: Tank Printer
                                                    • 4d: Parsing (Tracing)
                                                    • 4e: Parsing (Combinators)
                                                    • 4f: Parsing (Rule-Builders)
                                                    • 4g: Parsing (Outside Caller)
                                                    • 4h: Parsing (ASCII Glyphs)
                                                    • 4i: Parsing (Useful Idioms)
                                                    • 4j: Parsing (Bases and Base Digits)
                                                    • 4k: Atom Printing
                                                    • 4l: Atom Parsing
                                                    • 4m: Formatting Functions
                                                    • 4n: Virtualization
                                                    • 4o: Molds
                                                    • 5a: Compiler Utilities
                                                    • 5b: Macro Expansion
                                                    • 5c: Compiler Backend & Prettyprinter
                                                    • 5d: Parser
                                                    • 5e: Molds and mold builders
                                                    • 5f: Profiling support
                                                    • Runes

                                                      • Constants (Atoms and Strings)
                                                      • + lus · Arms
                                                      • | bar · Cores
                                                      • $ buc · Structures
                                                      • % cen · Calls
                                                      • : col · Cells
                                                      • . dot · Nock
                                                      • / fas · Imports
                                                      • ^ ket · Casts
                                                      • ; mic · Make
                                                      • ~ sig · Hints
                                                      • = tis · Subject
                                                      • ? wut · Conditionals
                                                      • ! zap · Wild
                                                      • --, == Terminators
                                                      • Limbs and wings

                                                        • Limbs
                                                        • Wings
                                                        • Zuse

                                                          • 2d(1-5): To JSON, Wains
                                                          • 2d(6): From JSON
                                                          • 2d(7): From JSON (unit)
                                                          • 2e(2-3): Print & Parse JSON
                                                          • 2m: Ordered Maps
                                                        • Arvo

                                                          • Overview
                                                          • Ames

                                                            • Overview
                                                            • Cryptography
                                                            • API Reference
                                                            • Scry Reference
                                                            • Data Types
                                                            • Behn

                                                              • Overview
                                                              • API Reference
                                                              • Scry Reference
                                                              • Examples
                                                              • Clay

                                                                • Overview
                                                                • Architecture
                                                                • Using Clay
                                                                • Data Types
                                                                • Scry Reference
                                                                • API Reference
                                                                • Examples
                                                                • Marks

                                                                  • Overview
                                                                  • Writing Marks
                                                                  • Using Marks
                                                                  • Examples
                                                                • Dill

                                                                  • Overview
                                                                  • API Reference
                                                                  • Scry Reference
                                                                  • Data Types
                                                                  • Eyre

                                                                    • Overview
                                                                    • External API Reference
                                                                    • Internal API Reference
                                                                    • Scry Reference
                                                                    • Data Types
                                                                    • Guide
                                                                    • Gall

                                                                      • Overview
                                                                      • API Reference
                                                                      • Data Types
                                                                      • Threads Reference
                                                                      • Iris

                                                                        • Overview
                                                                        • API Reference
                                                                        • Data Types
                                                                        • Example
                                                                        • Jael

                                                                          • Overview
                                                                          • API Reference
                                                                          • Scry Reference
                                                                          • Data Types
                                                                          • Examples
                                                                          • Khan

                                                                            • Overview
                                                                            • API Reference
                                                                            • Data Types
                                                                            • Example
                                                                            • Threads

                                                                              • Overview
                                                                              • HTTP API
                                                                              • Reference
                                                                              • Gall

                                                                                • Start Thread
                                                                                • Take Result
                                                                                • Take Facts
                                                                                • Stop Thread
                                                                                • Poke Thread
                                                                                • Examples

                                                                                  • Fetch JSON
                                                                                  • Child Thread
                                                                                  • Main-loop
                                                                                  • Poke Agent
                                                                                  • Scry
                                                                                  • Take Fact
                                                                                • Concepts

                                                                                  • Scries
                                                                                  • Subscriptions
                                                                                  • Tutorials

                                                                                    • Move Trace
                                                                                    • Reference

                                                                                      • Cryptography
                                                                                      • Filesystem Hierarchy
                                                                                    • Nock

                                                                                      • Nock Definition
                                                                                      • Explanation
                                                                                      • Example
                                                                                      • Implementations
                                                                                      • Vere

                                                                                        • C Runtime System
                                                                                        • Land of Nouns
                                                                                        • API overview by prefix
                                                                                        • C in Urbit
                                                                                        • Writing Jets
                                                                                        • Cryptography
                                                                                        • Azimuth

                                                                                          • Overview
                                                                                          • Urbit HD Wallet
                                                                                          • Azimuth Data Flow
                                                                                          • Azimuth.eth
                                                                                          • Ecliptic.eth
                                                                                          • Advanced Azimuth Tools
                                                                                          • Life and Rift
                                                                                          • Layer 2

                                                                                            • Layer 2 Overview
                                                                                            • Layer 2 Actions
                                                                                            • Transaction Format
                                                                                            • Rollers
                                                                                            • Roller HTTP RPC-API
                                                                                            • Custom Roller Tutorial
                                                                                          • Glossary

                                                                                            • Agent
                                                                                            • Ames
                                                                                            • API
                                                                                            • Aqua
                                                                                            • Arm
                                                                                            • Arvo
                                                                                            • Atom
                                                                                            • Aura
                                                                                            • Aural ASCII
                                                                                            • Azimuth
                                                                                            • Battery
                                                                                            • Behn
                                                                                            • Bowl
                                                                                            • Bridge
                                                                                            • Bunt
                                                                                            • Card
                                                                                            • Case
                                                                                            • Cask
                                                                                            • Cell
                                                                                            • Censures
                                                                                            • Claims
                                                                                            • Clay
                                                                                            • Cold atom
                                                                                            • Comet
                                                                                            • Commit
                                                                                            • Cons
                                                                                            • Context
                                                                                            • Cord
                                                                                            • Core
                                                                                            • Delegated Sending
                                                                                            • Desk
                                                                                            • Dill
                                                                                            • Document Proposal
                                                                                            • Dojo
                                                                                            • Door
                                                                                            • Double-boot
                                                                                            • Dry Gate
                                                                                            • Duct
                                                                                            • Ecliptic
                                                                                            • Entropy
                                                                                            • Event Log
                                                                                            • Eyre
                                                                                            • Face
                                                                                            • Fact
                                                                                            • Foo Bar Baz
                                                                                            • Galaxy
                                                                                            • Gall
                                                                                            • Garden
                                                                                            • Gate
                                                                                            • Generator
                                                                                            • Gift
                                                                                            • Glob
                                                                                            • HD Wallet
                                                                                            • Helm
                                                                                            • Hood
                                                                                            • Hoon
                                                                                            • Invite Tree
                                                                                            • Iris
                                                                                            • Jael
                                                                                            • Jet
                                                                                            • Kelvin versioning
                                                                                            • Kelvin versioning
                                                                                            • Keyfile
                                                                                            • Keywords
                                                                                            • Khan
                                                                                            • Kiln
                                                                                            • Landscape
                                                                                            • Leg
                                                                                            • List
                                                                                            • Loobean
                                                                                            • Lull
                                                                                            • Mark
                                                                                            • Metals
                                                                                            • Mold
                                                                                            • Monad
                                                                                            • Moon
                                                                                            • Move
                                                                                            • Nock
                                                                                            • Noun
                                                                                            • ~
                                                                                            • OTA Updates
                                                                                            • Path Prefix
                                                                                            • Path
                                                                                            • @p
                                                                                            • Payload
                                                                                            • Peek
                                                                                            • pH
                                                                                            • Pier
                                                                                            • Pill
                                                                                            • Planet
                                                                                            • Poke
                                                                                            • Proxies
                                                                                            • Replay
                                                                                            • Factory Reset
                                                                                            • Roller
                                                                                            • Naive rollups
                                                                                            • Rune
                                                                                            • Runtime
                                                                                            • Sail
                                                                                            • Sample
                                                                                            • Scry
                                                                                            • Senate
                                                                                            • Ship
                                                                                            • Slam
                                                                                            • Spider
                                                                                            • Sponsor
                                                                                            • Star
                                                                                            • String
                                                                                            • Subject Oriented Programming
                                                                                            • Subject
                                                                                            • Subscription
                                                                                            • Tape
                                                                                            • Thread
                                                                                            • Trap
                                                                                            • Udon
                                                                                            • Upgrade Proposal
                                                                                            • Userspace
                                                                                            • Vane
                                                                                            • Vase
                                                                                            • Vere
                                                                                            • Voting
                                                                                            • Warm atom
                                                                                            • Wet Gate
                                                                                            • Wing
                                                                                            • Wire
                                                                                            • Wrapper
                                                                                            • ~zod
                                                                                            • Zuse
                                                                                            • Additional

                                                                                              • Cryptography
                                                                                              • Mips (Maps of Maps)
                                                                                              • Software Distribution

                                                                                                • Overview
                                                                                                • Docket File
                                                                                                • Glob
                                                                                              Reference/Arvo/Eyre

                                                                                              External API Reference

                                                                                              This document contains reference information about Eyre's external APIs including the channel system and scries. Each section will also have practical examples in the Guide document.

                                                                                              Authentication

                                                                                              To use Eyre's channel system, run threads or perform scries you must first obtain a session cookie by authenticating with the following HTTP request:

                                                                                              HTTP MethodDataURL PathNotes
                                                                                              POSTpassword=lidlut-tabwed-pillex-ridrup/~/loginThe password is your web login code which can be obtained with +code in the dojo.

                                                                                              See the Guide for an example of how to do this using the curl.

                                                                                              Eyre's response will include a set-cookie header like:

                                                                                              set-cookie: urbauth-~zod=0v4.ilskp.psv00.t09r0.l8rps.3n97v; Path=/; Max-Age=604800

                                                                                              The urbauth-{...} cookie provided must be included in a cookie header with all subsequent requests like:

                                                                                              cookie: urbauth-~zod=0v4.ilskp.psv00.t09r0.l8rps.3n97v

                                                                                              Channels

                                                                                              Eyre's channel system is the primary way of interacting with Gall agents from outside of Urbit.

                                                                                              Data from an external HTTP client is sent to Eyre as an HTTP PUT request containing one or more action JSON objects. Clients must obtain a session cookie by authenticating with Eyre in order to make such requests.

                                                                                              Data from Eyre is sent back to the external HTTP client on a channel as SSEs (Server Sent Events) containing a response JSON object.

                                                                                              A new channel is automatically created whenever a client sends an action in an HTTP PUT request to http{s}://{host}{port}/~/channel/{uid} with a new uid. To connect to the channel and receive any pending events, you just send an HTTP GET request with a valid session cookie to that URL.

                                                                                              The response you'll get to the GET request will be an event stream. Events will come in like:

                                                                                              id: 0
                                                                                              data: {"ok":"ok","id":1,"response":"poke"}

                                                                                              If you're working with Javascript in the browser context you'll handle these with an EventSource object or by using fetch and ReadableStream. If you're using another language, there'll likely be a library available to handle SSEs.

                                                                                              All the events that Eyre sends you on a channel must be acked so that Eyre can forget about them and clear them from the channel state. If facts (as diffs) from Gall agents to which you've subscribed are left unacked long enough, Eyre will consider the particular subscription clogged and automatically unsubscribe you. Note that acking one event will implicitly ack all previous events.

                                                                                              When you're finished with a channel, you can send Eyre a delete action to close it.

                                                                                              See the Using the Channel System section of the Guide document for a practical example.

                                                                                              HTTP Requests

                                                                                              Actions are sent to Eyre in HTTP PUT requests:

                                                                                              HTTP MethodRequired HeadersDataURL Path
                                                                                              PUTContent-Type & CookieOne or more actions wrapped in a JSON array ([])/~/channel/{uid}

                                                                                              The cookie header contains the session cookie obtained by authenticating. The data is a JSON array containing one or more JSON action objects. The channel uid is a unique name of your choosing. Typically you'd use the current unix time and a hash but there's no specific requirements. If you're opening a new channel you'd choose a new uid and if you already have a channel open you'd just use that.

                                                                                              If successful, Eyre will respond with a status code of 204. Note the HTTP response will have no content, any responses will be sent as SSEs on the channel event stream.

                                                                                              Actions

                                                                                              Poke

                                                                                              This is for poking a Gall agent.

                                                                                              KeyJSON TypeExample ValueDescription
                                                                                              idNumber1ID for keeping track of sent messages.
                                                                                              actionString'poke'The kind of action.
                                                                                              shipString'zod'Target ship name, excluding leading ~.
                                                                                              appString'hood'Name of the gall agent you're poking.
                                                                                              markString'helm-hi'Type of data. Must correspond to a mark definition in /mar.
                                                                                              jsonAny'hello'Actual payload. Any JSON type, determined by app.

                                                                                              Example

                                                                                              {
                                                                                              "id": 1,
                                                                                              "action": "poke",
                                                                                              "ship": "zod",
                                                                                              "app": "hood",
                                                                                              "mark": "helm-hi",
                                                                                              "json": "hello"
                                                                                              }

                                                                                              Response

                                                                                              Eyre will send a poke ack as an SSE event on the channel event stream.

                                                                                              Subscribe

                                                                                              This is for subscribing to a watch path of a Gall agent.

                                                                                              KeyJSON TypeExample ValueDescription
                                                                                              idNumber2ID for keeping track of sent messages.
                                                                                              actionString'subscribe'The kind of action.
                                                                                              shipString'zod'Target ship name, excluding leading ~.
                                                                                              appString'graph-store'Name of the gall agent to which you're subscribing.
                                                                                              pathString'/updates'The path to watch. Depends on the app.

                                                                                              Example

                                                                                              {
                                                                                              "id": 2,
                                                                                              "action": "subscribe",
                                                                                              "ship": "zod",
                                                                                              "app": "graph-store",
                                                                                              "path": "/updates"
                                                                                              }

                                                                                              Response

                                                                                              Eyre will send back a watch ack. If subscribing was successful, you will also begin receiving any diffs sent by the Gall agent on the specified path.

                                                                                              Ack

                                                                                              This is for acknowledging an SSE event. If you ack one event, you also implicitly ack all previous events. Events must be acked so that Eyre can forget them. If you leave facts (as diffs) unacked long enough, Eyre will consider the subscription clogged and automatically unsubscribe you.

                                                                                              KeyJSON TypeExample ValueDescription
                                                                                              idNumber3ID for keeping track of sent messages.
                                                                                              actionString'ack'The kind of action.
                                                                                              event-idNumber7ID of SSE event up to which you're acknowledging receipt

                                                                                              Example

                                                                                              {
                                                                                              "id": 3,
                                                                                              "action": "ack",
                                                                                              "event-id": 7
                                                                                              }

                                                                                              Response

                                                                                              Eyre will not respond to an ack action.

                                                                                              Unsubscribe

                                                                                              This is for unsubscribing from a Gall agent watch path to which you've previously subscribed.

                                                                                              KeyJSON TypeExample ValueDescription
                                                                                              idNumber4ID for keeping track of sent messages.
                                                                                              actionStringunsubscribeThe kind of action.
                                                                                              subscriptionNumber2Request ID of the initial subscribe action from earlier.

                                                                                              Example

                                                                                              {
                                                                                              "id": 4,
                                                                                              "action": "unsubscribe",
                                                                                              "subscription": 2
                                                                                              }

                                                                                              Response

                                                                                              Eyre will not respond to an unsubscribe action.

                                                                                              Delete Channel

                                                                                              This is for deleting the channel itself.

                                                                                              KeyJSON TypeExample ValueDescription
                                                                                              idNumber5ID for keeping track of sent messages.
                                                                                              actionString'delete'The kind of action.

                                                                                              Example

                                                                                              {
                                                                                              "id": 5,
                                                                                              "action": "delete"
                                                                                              }

                                                                                              Response

                                                                                              Eyre will not respond to a delete action.

                                                                                              Responses

                                                                                              Poke Ack

                                                                                              This acknowledgement comes in response to a poke action. A poke ack with an ok key means the poke succeeded. A poke ack with an err key means the poke failed.

                                                                                              Positive Poke Ack

                                                                                              KeyJSON TypeExample ValueDescription
                                                                                              okString'ok'Positive acknowledgement.
                                                                                              idNumber1Request ID of the poke being acknowledged.
                                                                                              responseString'poke'The kind of action being acknowledged.

                                                                                              Example

                                                                                              {
                                                                                              "ok": "ok",
                                                                                              "id": 1,
                                                                                              "response": "poke"
                                                                                              }

                                                                                              Negative Poke Ack

                                                                                              KeyJSON TypeExample ValueDescription
                                                                                              errString'some text...'Negative acknowledgement. Contains an error message and/or traceback.
                                                                                              idNumber1Request ID of the poke being acknowledged.
                                                                                              responseString'poke'The kind of action being acknowledged.

                                                                                              Example

                                                                                              {
                                                                                              "err": "<error message and traceback>",
                                                                                              "id": 1,
                                                                                              "response": "poke"
                                                                                              }

                                                                                              Action Required

                                                                                              You must ack the event.

                                                                                              Watch Ack

                                                                                              This acknowledgement comes in response to a subscribe action. A watch ack with an ok key means the subscription was successful. A watch ack with an err key means the subscription failed.

                                                                                              Positive Watch Ack

                                                                                              KeyJSON TypeExample ValueDescription
                                                                                              okString'ok'Positive acknowledgement.
                                                                                              idNumber2Request ID of the initial subscribe action.
                                                                                              responseString'subscribe'The kind of action being acknowledged.

                                                                                              Example

                                                                                              {
                                                                                              "ok": "ok",
                                                                                              "id": 2,
                                                                                              "response": "subscribe"
                                                                                              }

                                                                                              Negative Watch Ack

                                                                                              KeyJSON TypeExample ValueDescription
                                                                                              errString'some text...'Negative acknowledgement. Contains an error message and/or traceback.
                                                                                              idNumber2Request ID of the initial subscribe action.
                                                                                              responseString'subscribe'The kind of action being acknowledged.

                                                                                              Example

                                                                                              {
                                                                                              "err": "<error message and traceback>",
                                                                                              "id": 2,
                                                                                              "response": "subscribe"
                                                                                              }

                                                                                              Action Required

                                                                                              You must ack the event.

                                                                                              Diff

                                                                                              All facts sent by a Gall agent on the path to which you've subscribed are delivered as diffs. Note that Eyre makes a best effort to convert the fact to a json mark. If it can't, Eyre will crash and close the subscription, and you won't receive any diff for the fact.

                                                                                              KeyJSON TypeExample ValueDescription
                                                                                              jsonAny{'foo': 'bar'}The actual data from the agent, could be any JSON structure.
                                                                                              idNumber3Request ID of the initial subscribe action from earlier.
                                                                                              responseString'diff'The kind of response. All facts are marked 'diff'.

                                                                                              Example

                                                                                              {
                                                                                              "json": { "foo": "bar" },
                                                                                              "id": 3,
                                                                                              "response": "diff"
                                                                                              }

                                                                                              Action Required

                                                                                              You must ack each diff that comes in the event stream.

                                                                                              Quit

                                                                                              A quit comes in when a subscription has been ended. You may be intentionally kicked by the Gall agent to which you're subscribed, but certain network conditions can also trigger a quit. As a result, it's best to try and resubscribe when you get a quit, and if the resulting watch ack is negative you can then conclude the quit was intentional and give up.

                                                                                              KeyJSON TypeExample ValueDescription
                                                                                              idNumber4Request ID of the initial subscribe action.
                                                                                              responseString'quit'The kind of response.

                                                                                              Example

                                                                                              {
                                                                                              "id": 4,
                                                                                              "response": "quit"
                                                                                              }

                                                                                              Action Required

                                                                                              You must ack the event and you may wish to try and resubscribe.

                                                                                              Scry

                                                                                              A scry is a read-only request for some data.

                                                                                              A scry takes the form of an authenticated HTTP GET request to a URL path with the following format:

                                                                                              http{s}://{host}/~/scry/{app}{path}.{mark}

                                                                                              The {app} is the name of the Gall agent you want to query, for example graph-store.

                                                                                              The {path} is a scry endpoint of the Gall agent in question. Eyre will always scry with a care of %x, so the {path} needn't specify that. For example, the /x/keys scry endpoint of graph-store would just be specified as keys.

                                                                                              The {mark} is the type you want returned. It needn't just be json as with the channel system, it can be any mark, with two conditions:

                                                                                              1. It must be possible to convert the mark produced by the specified scry endpoint to the mark you want returned.
                                                                                              2. It must be possible to convert the mark you want returned to a mime mark, otherwise Eyre can't encode it in the HTTP response.

                                                                                              If your session cookie is invalid or missing, Eyre will respond with a 403 Forbidden status. If the scry endpoint cannot be found, Eyre will respond with a 404 Missing status. If the mark conversions can't be done, Eyre will respond with a 500 Internal Server Error status. Otherwise, Eyre will respond with a 200 OK status with the requested data in the body of the HTTP response.

                                                                                              See the Scrying section of the Guide document for a practical example.

                                                                                              Spider

                                                                                              See the HTTP API section of the Threads documentation.

                                                                                              <-

                                                                                              Overview

                                                                                              Internal API Reference

                                                                                              ->

                                                                                              Edit this page on GitHub

                                                                                              Last modified March 17, 2023