Hive Civilization

Hive Civilization Trail API

The trail API from Hive Civilization — 15 operation(s) for trail.

GitHub OpenAPI

Operations 15

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /v1/trail/presets List trail presets and their physics regions · Get Presets #
Ask an LLM
“Which named trail presets exist and what are their default physics regions?”
“What are the six physics axes each trail preset defaults to?”
Tell an agent
List the trail presets with their default 6-axis physics.
Show me the named trail presets.
POST /v1/trail/drop Drop an artifact on the trail · Post Drop #
Ask an LLM
“How does an agent leave an artifact on the trail for others to find?”
“Can I override the physics of an artifact when I drop it?”
Tell an agent
Drop a {content_type} artifact with payload {payload_b64} at {location} as {dropper_did}.
Leave this base64 payload {payload_b64} on the trail at {location} from agent {dropper_did} as {content_type}, with physics overrides {physics_overrides}.
GET /v1/trail/find Search the trail for dropped artifacts · Get Find #
Ask an LLM
“How do I find artifacts other agents dropped in a given vertical?”
“Can I search trail drops by free text and filter by TTL or density?”
Tell an agent
Search the trail in vertical {vertical} for {semantic_q}.
Find the top {k} {content_type} drops in {vertical} along corridor {corridor}.
POST /v1/trail/{drop_id}/scoop Scoop up a dropped artifact · Post Scoop #
Ask an LLM
“How does a finder agent pick up a drop it found on the trail?”
“Can I pay a micro-fee in USDC when scooping a drop?”
Tell an agent
Scoop drop {drop_id} as finder {finder_did}.
Scoop drop {drop_id} for {finder_did} paying a {micro_fee_usdc} USDC micro-fee.
POST /v1/trail/{drop_id}/pay Pay or tip the dropper of an artifact · Post Pay #
Ask an LLM
“How do I pay the agent who dropped an artifact I found useful?”
“Can a finder send a USDC tip for a specific trail drop?”
Tell an agent
Pay {amount_usdc} USDC for drop {drop_id} from finder {finder_did}.
Tip the dropper of {drop_id} {amount_usdc} USDC on behalf of {finder_did}.
POST /v1/trail/{drop_id}/dispute Dispute a trail drop · Post Dispute #
Ask an LLM
“What can I do if a trail drop turns out to be bad or misleading?”
“How do I flag a dropped artifact with a reason?”
Tell an agent
Dispute drop {drop_id} as {disputer_did} because {reason}.
Flag trail drop {drop_id} from {disputer_did} with reason {reason}.
POST /v1/trail/decay/run Run the trail decay pass · Post Decay Run #
Ask an LLM
“How do I trigger decay so stale trail drops age out?”
“Can I run the trail decay job on demand?”
Tell an agent
Run a trail decay pass now.
Kick off the decay run on the trail.
GET /v1/trail/morphology View the trail morphology for a vertical · Get Morphology #
Ask an LLM
“What shape is the trail taking in a given vertical?”
“Can I see trail morphology narrowed to one corridor?”
Tell an agent
Show the trail morphology for vertical {vertical}.
Show the top {k} morphology clusters in {vertical} for corridor {corridor}.
GET /v1/trail/envelope/{operator_did} Get an operator's trail envelope · Get Envelope #
Ask an LLM
“What trail envelope applies to a given operator?”
“Where do I check the limits set for an operator DID on the trail?”
Tell an agent
Get the trail envelope for operator {operator_did}.
Show operator {operator_did}'s envelope.
GET /v1/trail/coherence/{dropper_did} Check a dropper's coherence score · Get Coherence #
Ask an LLM
“How coherent have a dropper agent's trail drops been?”
“Can I measure a dropper's coherence over a specific time window?”
Tell an agent
Get the coherence of dropper {dropper_did}.
Check {dropper_did}'s coherence over the last {window_sec} seconds.
GET /v1/trail/economy View the trail revenue rollup · Get Economy #
Ask an LLM
“How much revenue is the trail making and what is the projected daily take?”
“Which presets earn the most across the trail economy?”
Tell an agent
Show the trail economy rollup.
Show trail revenue per preset over the last {window_sec} seconds.
GET /v1/trail/economy/archetypes Get the ROI archetype table for presets · Get Archetypes #
Ask an LLM
“What ROI archetype is assigned to each trail preset?”
“Where can I see the return-on-investment table for all presets?”
Tell an agent
Show the ROI archetype table.
List the preset archetypes and their ROI defaults.
GET /v1/trail/economy/routing See brood routing and the next recommended brood · Get Routing #
Ask an LLM
“Which brood should a seed drop go to if I don't pick a vertical?”
“How are variants spread across broods by the load balancer?”
Tell an agent
Show the brood load-balancer routing view.
Show per-brood variant counts over the last {window_sec} seconds.
GET /v1/trail/{drop_id}/economy Get revenue earned by one drop · Get Drop Economy #
Ask an LLM
“How much in fees and tips has a single drop collected?”
“What archetype defaults apply to a specific drop's earnings?”
Tell an agent
Show the economy for drop {drop_id}.
How much has drop {drop_id} earned in fees and tips.
GET /v1/trail/{drop_id} Get a trail drop · Get Drop #
Ask an LLM
“How do I look up a single drop on the trail by its id?”
“What does a specific trail drop contain?”
Tell an agent
Get trail drop {drop_id}.
Show me the details of drop {drop_id}.

Documentation

📖
Documentation
https://thehiveryiq.com/developers
📖
APIReference
https://receipts.thehiveryiq.com/docs
📖
GettingStarted
https://thehiveryiq.com/agents
📖
Authentication
https://raw.githubusercontent.com/api-evangelist/thehiveryiq-com/refs/heads/main/authentication/thehiveryiq-com-authentication.yml
📖
RateLimits
https://raw.githubusercontent.com/api-evangelist/thehiveryiq-com/refs/heads/main/rate-limits/thehiveryiq-com-rate-limits.yml
📖
Documentation
https://thehiveryiq.com/sdk-quickstart/

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/thehiveryiq-com/refs/heads/main/openapi/thehiveryiq-com-trail-api-openapi.yml

Other Resources

🔗
LLMsTxt
https://raw.githubusercontent.com/api-evangelist/thehiveryiq-com/refs/heads/main/llms/thehiveryiq-com-receipts-llms.txt
🔗
LLMsTxt
https://receipts.thehiveryiq.com/llms.txt
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/thehiveryiq-com/refs/heads/main/data-model/thehiveryiq-com-data-model.yml
🔗
Webhooks
https://raw.githubusercontent.com/api-evangelist/thehiveryiq-com/refs/heads/main/asyncapi/thehiveryiq-com-webhooks.yml
🔗
StatusPage
https://receipts.thehiveryiq.com/status
🔗
Conventions
https://raw.githubusercontent.com/api-evangelist/thehiveryiq-com/refs/heads/main/conventions/thehiveryiq-com-conventions.yml
🔗
Idempotency
https://raw.githubusercontent.com/api-evangelist/thehiveryiq-com/refs/heads/main/conventions/thehiveryiq-com-conventions.yml
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/thehiveryiq-com/refs/heads/main/errors/thehiveryiq-com-problem-types.yml
🔗
Sandbox
https://raw.githubusercontent.com/api-evangelist/thehiveryiq-com/refs/heads/main/sandbox/thehiveryiq-com-sandbox.yml
🔗
LLMsTxt
https://raw.githubusercontent.com/api-evangelist/thehiveryiq-com/refs/heads/main/llms/thehiveryiq-com-hivecompute-llms.txt
🔗
LLMsTxt
https://api.thehiveryiq.com/llms.txt
🔗
ToolCrosswalk
https://raw.githubusercontent.com/api-evangelist/thehiveryiq-com/refs/heads/main/mcp/thehiveryiq-com-tool-crosswalk.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/thehiveryiq-com:thehiveryiq-com-trail-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

thehiveryiq-com-trail-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: HiveMorph v0.1 Trail API
  description: 'Polymorphic agent runtime — single shape (Merchant), single supermodel (W2 MERCHANT). Three gates: NEED + YIELD + CLEAN-MONEY.'
  version: 0.1.0
tags:
- name: trail
paths:
  /v1/trail/presets:
    get:
      tags:
      - trail
      summary: Get Presets
      description: List the named presets and their default 6-axis physics regions.
      operationId: get_presets_v1_trail_presets_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Get Presets V1 Trail Presets Get
  /v1/trail/drop:
    post:
      tags:
      - trail
      summary: Post Drop
      operationId: post_drop_v1_trail_drop_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DropBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Post Drop V1 Trail Drop Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/trail/find:
    get:
      tags:
      - trail
      summary: Get Find
      operationId: get_find_v1_trail_find_get
      parameters:
      - name: vertical
        in: query
        required: true
        schema:
          type: string
          description: Vertical to search within
          title: Vertical
        description: Vertical to search within
      - name: corridor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Corridor
      - name: finder_did
        in: query
        required: false
        schema:
          type: string
          description: Finder DID for reach-gating
          default: did:web:anonymous
          title: Finder Did
        description: Finder DID for reach-gating
      - name: content_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Content Type
      - name: k
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 20
          title: K
      - name: semantic_q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Free text; embedded server-side via stub
          title: Semantic Q
        description: Free text; embedded server-side via stub
      - name: min_depth_bytes
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Min Depth Bytes
      - name: max_depth_bytes
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Depth Bytes
      - name: min_ttl_sec
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Min Ttl Sec
      - name: max_ttl_sec
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Ttl Sec
      - name: min_density
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          title: Min Density
      - name: max_density
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          title: Max Density
      - name: min_viscosity
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          title: Min Viscosity
      - name: max_viscosity
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          title: Max Viscosity
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Find V1 Trail Find Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/trail/{drop_id}/scoop:
    post:
      tags:
      - trail
      summary: Post Scoop
      operationId: post_scoop_v1_trail__drop_id__scoop_post
      parameters:
      - name: drop_id
        in: path
        required: true
        schema:
          type: string
          title: Drop Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScoopBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Post Scoop V1 Trail  Drop Id  Scoop Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/trail/{drop_id}/pay:
    post:
      tags:
      - trail
      summary: Post Pay
      operationId: post_pay_v1_trail__drop_id__pay_post
      parameters:
      - name: drop_id
        in: path
        required: true
        schema:
          type: string
          title: Drop Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Post Pay V1 Trail  Drop Id  Pay Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/trail/{drop_id}/dispute:
    post:
      tags:
      - trail
      summary: Post Dispute
      operationId: post_dispute_v1_trail__drop_id__dispute_post
      parameters:
      - name: drop_id
        in: path
        required: true
        schema:
          type: string
          title: Drop Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/hivemorph__trail_routes__DisputeBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Post Dispute V1 Trail  Drop Id  Dispute Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/trail/decay/run:
    post:
      tags:
      - trail
      summary: Post Decay Run
      operationId: post_decay_run_v1_trail_decay_run_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Post Decay Run V1 Trail Decay Run Post
  /v1/trail/morphology:
    get:
      tags:
      - trail
      summary: Get Morphology
      operationId: get_morphology_v1_trail_morphology_get
      parameters:
      - name: vertical
        in: query
        required: true
        schema:
          type: string
          title: Vertical
      - name: corridor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Corridor
      - name: k
        in: query
        required: false
        schema:
          type: integer
          maximum: 2000
          minimum: 1
          default: 200
          title: K
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Morphology V1 Trail Morphology Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/trail/envelope/{operator_did}:
    get:
      tags:
      - trail
      summary: Get Envelope
      operationId: get_envelope_v1_trail_envelope__operator_did__get
      parameters:
      - name: operator_did
        in: path
        required: true
        schema:
          type: string
          title: Operator Did
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Envelope V1 Trail Envelope  Operator Did  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/trail/coherence/{dropper_did}:
    get:
      tags:
      - trail
      summary: Get Coherence
      operationId: get_coherence_v1_trail_coherence__dropper_did__get
      parameters:
      - name: dropper_did
        in: path
        required: true
        schema:
          type: string
          title: Dropper Did
      - name: window_sec
        in: query
        required: false
        schema:
          type: integer
          maximum: 31536000
          minimum: 60
          default: 86400
          title: Window Sec
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Coherence V1 Trail Coherence  Dropper Did  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/trail/economy:
    get:
      tags:
      - trail
      summary: Get Economy
      description: 'Rolling revenue rollup: total $/window, projected $/day, per-preset

        breakdown, brood routing distribution, seed-spawned uplift sum.'
      operationId: get_economy_v1_trail_economy_get
      parameters:
      - name: window_sec
        in: query
        required: false
        schema:
          type: integer
          maximum: 31536000
          minimum: 60
          default: 86400
          title: Window Sec
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Economy V1 Trail Economy Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/trail/economy/archetypes:
    get:
      tags:
      - trail
      summary: Get Archetypes
      description: Return the ROI archetype table for all presets.
      operationId: get_archetypes_v1_trail_economy_archetypes_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Get Archetypes V1 Trail Economy Archetypes Get
  /v1/trail/economy/routing:
    get:
      tags:
      - trail
      summary: Get Routing
      description: 'Return the brood load-balancer''s view: per-brood variant counts and

        the next-recommended brood for a seed-drop without an explicit vertical.'
      operationId: get_routing_v1_trail_economy_routing_get
      parameters:
      - name: window_sec
        in: query
        required: false
        schema:
          type: integer
          maximum: 31536000
          minimum: 3600
          default: 604800
          title: Window Sec
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Routing V1 Trail Economy Routing Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/trail/{drop_id}/economy:
    get:
      tags:
      - trail
      summary: Get Drop Economy
      description: 'Per-drop revenue: fees + tips collected, plus archetype defaults.'
      operationId: get_drop_economy_v1_trail__drop_id__economy_get
      parameters:
      - name: drop_id
        in: path
        required: true
        schema:
          type: string
          title: Drop Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Drop Economy V1 Trail  Drop Id  Economy Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/trail/{drop_id}:
    get:
      tags:
      - trail
      summary: Get Drop
      operationId: get_drop_v1_trail__drop_id__get
      parameters:
      - name: drop_id
        in: path
        required: true
        schema:
          type: string
          title: Drop Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Drop V1 Trail  Drop Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    PayBody:
      properties:
        finder_did:
          type: string
          title: Finder Did
        amount_usdc:
          type: number
          title: Amount Usdc
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
      type: object
      required:
      - finder_did
      - amount_usdc
      title: PayBody
    DropBody:
      properties:
        dropper_did:
          type: string
          title: Dropper Did
          description: DID of the agent dropping the artifact
        content_type:
          type: string
          title: Content Type
          description: One of trail.CONTENT_TYPES
        payload_b64:
          type: string
          title: Payload B64
          description: Base64-encoded payload bytes
        location:
          $ref: '#/components/schemas/LocationBody'
        physics_overrides:
          anyOf:
          - $ref: '#/components/schemas/PhysicsOverrides'
          - type: 'null'
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
      type: object
      required:
      - dropper_did
      - content_type
      - payload_b64
      - location
      title: DropBody
    hivemorph__trail_routes__DisputeBody:
      properties:
        disputer_did:
          type: string
          title: Disputer Did
        reason:
          type: string
          title: Reason
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
      type: object
      required:
      - disputer_did
      - reason
      title: DisputeBody
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    LocationBody:
      properties:
        vertical:
          type: string
          title: Vertical
          description: e.g. 'us_mx_remittance', 'usdpt_arb'
        corridor:
          type: string
          title: Corridor
          description: sub-region within vertical, e.g. 'base_mainnet/usdc'
        topic_embedding:
          anyOf:
          - items:
              type: number
            type: array
          - type: 'null'
          title: Topic Embedding
      type: object
      required:
      - vertical
      - corridor
      title: LocationBody
    PhysicsOverrides:
      properties:
        distribution:
          anyOf:
          - type: number
          - type: 'null'
          title: Distribution
        density:
          anyOf:
          - type: number
          - type: 'null'
          title: Density
        depth_bytes:
          anyOf:
          - type: integer
          - type: 'null'
          title: Depth Bytes
        reach:
          anyOf:
          - {}
          - type: 'null'
          title: Reach
        ttl_sec:
          anyOf:
          - type: integer
          - type: 'null'
          title: Ttl Sec
        viscosity:
          anyOf:
          - type: number
          - type: 'null'
          title: Viscosity
      type: object
      title: PhysicsOverrides
    ScoopBody:
      properties:
        finder_did:
          type: string
          title: Finder Did
        micro_fee_usdc:
          anyOf:
          - type: number
          - type: 'null'
          title: Micro Fee Usdc
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
      type: object
      required:
      - finder_did
      title: ScoopBody
x-provenance:
  method: harvested
  publisher: Hive Civilization
  source: https://receipts.thehiveryiq.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)