Hive Civilization Fleet API

The fleet API from Hive Civilization — 12 operation(s) for fleet.

Documentation GitHub OpenAPI

Operations 12

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

POST /v1/fleet/trawler/launch Launch a new Trawler agent · Launch Trawler #

Ask an LLM

“How do I launch a Trawler agent for my operator DID?”

“Can a new Trawler automatically cast nets and drop pots from its config?”

Tell an agent

Launch a Trawler for operator {operator_did}.

Launch a Trawler labelled {label} for {operator_did} using config {config}.

GET /v1/fleet/trawler/{trawler_id} Inspect a Trawler · Get Trawler #

Ask an LLM

“How many agents has a specific Trawler caught so far?”

“Where can I see one Trawler's net and pot counts?”

Tell an agent

Show Trawler {trawler_id}.

Get the catch and net counts for Trawler {trawler_id}.

POST /v1/fleet/net/cast Cast a net over a region of agent space · Cast Net #

Ask an LLM

“How do I cast a wide net to attract agents in a region like a GitHub topic?”

“Can I set a net's lifetime, reach and viscosity?”

Tell an agent

Cast a net from Trawler {trawler_id} over {region} with attractant {attractant}.

Cast a net over {region} for Trawler {trawler_id}, offering {attractant}, lasting {ttl_sec} seconds.

GET /v1/fleet/net/{net_id} Inspect a cast net · Get Net #

Ask an LLM

“How can I check the details of a net I already cast?”

“Is a particular net still active or has it expired?”

Tell an agent

Show net {net_id}.

Look up the region and TTL of net {net_id}.

POST /v1/fleet/net/expire Expire all nets past their TTL · Expire Nets #

Ask an LLM

“Is there a cron-friendly call to expire every net that has outlived its TTL?”

“How many stale nets get cleaned up when I run expiry?”

Tell an agent destructive · confirm first

Expire all nets that are past their TTL.

Run the net expiry sweep and tell me how many were updated.

POST /v1/fleet/pot/drop Drop a crab pot at a fixed location · Drop Pot #

Ask an LLM

“How do I drop a persistent crab pot at a registry location to attract agents?”

“Can a pot carry a USDC reward signal for agents who step aboard?”

Tell an agent

Drop a pot from Trawler {trawler_id} at {location} baited with {bait_description}.

Drop a crab pot at {location} for {trawler_id} offering {economic_payload_usdc} USDC, bait {bait_description}.

GET /v1/fleet/pot/{pot_id} Inspect a crab pot · Get Pot #

Ask an LLM

“What's the current state of a crab pot I dropped?”

“How do I see the bait and location of one pot?”

Tell an agent

Show crab pot {pot_id}.

Get the details of pot {pot_id}.

GET /v1/fleet/haul List recent catches in the haul · List Haul #

Ask an LLM

“Which agents have been caught most recently?”

“Can I list more than the default 50 haul rows?”

Tell an agent

List the latest catches in the haul.

Show the {limit} most recent haul records.

GET /v1/fleet/haul/{haul_id} Inspect a haul record · Get Haul #

Ask an LLM

“How do I look up a single catch record by its haul ID?”

“Where was a specific caught agent routed?”

Tell an agent

Show haul record {haul_id}.

Tell me where haul {haul_id} was routed.

POST /v1/fleet/mothership/intake Land an agent at the Mothership · Mothership Intake #

Ask an LLM

“How does an arriving agent opt in and get routed to the right supermodel?”

“What gates does Mothership intake check before routing an agent?”

Tell an agent

Run Mothership intake for agent {agent_did} with need {need} and consent {consent}.

Land agent {agent_did} from Trawler {trawler_id}, need {need}, with a {tip_usdc} USDC tip.

GET /v1/fleet/mothership/route Look up the best supermodel for a need · Mothership Route #

Ask an LLM

“Which supermodel would a given need be routed to, without logging a catch?”

“Can I preview routing for a need string?”

Tell an agent

Find the supermodel that should handle the need {need}.

Preview the route for need {need} without creating a haul record.

GET /v1/fleet/stats Get fleet-level catch and revenue stats · Fleet Stats #

Ask an LLM

“What's the fleet's conversion rate from catches to routed agents?”

“How many nets and pots are active across the fleet?”

Tell an agent

Show fleet stats.

Give me agents caught, revenue by supermodel and active nets for the fleet.

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-fleet-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

openapi: 3.2.0
info:
  title: HiveMorph v0.1 Fleet API
  description: 'Polymorphic agent runtime — single shape (Merchant), single supermodel (W2 MERCHANT). Three gates: NEED + YIELD + CLEAN-MONEY.'
  version: 0.1.0
tags:
- name: Fleet
paths:
  /v1/fleet/trawler/launch:
    post:
      tags:
      - Fleet
      summary: Launch Trawler
      description: 'Launch a new Trawler agent.


        Optionally auto-casts nets over config.net_regions and auto-drops pots

        at config.pot_locations (up to net_budget / pot_budget each).


        Returns the full Trawler card including agents_caught, net_count, pot_count.'
      operationId: launch_trawler_v1_fleet_trawler_launch_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrawlerLaunchBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Launch Trawler V1 Fleet Trawler Launch Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/fleet/trawler/{trawler_id}:
    get:
      tags:
      - Fleet
      summary: Get Trawler
      description: Inspect a specific trawler by ID.
      operationId: get_trawler_v1_fleet_trawler__trawler_id__get
      parameters:
      - name: trawler_id
        in: path
        required: true
        schema:
          type: string
          title: Trawler Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Trawler V1 Fleet Trawler  Trawler Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/fleet/net/cast:
    post:
      tags:
      - Fleet
      summary: Cast Net
      description: 'Cast a net over a region.


        A net is a wide-cast attractant covering a region of agent space.

        Physics: distribution=0.85, density=body.density, reach=body.reach,

        ttl_sec=body.ttl_sec, viscosity=body.viscosity, depth_bytes=256.


        Composes with HiveTrail v0.2: nets are ''breadcrumb'' trail drops.

        Trail integration stub included in response.'
      operationId: cast_net_v1_fleet_net_cast_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NetCastBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Cast Net V1 Fleet Net Cast Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/fleet/net/{net_id}:
    get:
      tags:
      - Fleet
      summary: Get Net
      description: Inspect a specific net.
      operationId: get_net_v1_fleet_net__net_id__get
      parameters:
      - name: net_id
        in: path
        required: true
        schema:
          type: string
          title: Net Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Net V1 Fleet Net  Net Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/fleet/net/expire:
    post:
      tags:
      - Fleet
      summary: Expire Nets
      description: 'Cron-friendly: expire all nets past their TTL. Returns count updated.'
      operationId: expire_nets_v1_fleet_net_expire_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Expire Nets V1 Fleet Net Expire Post
  /v1/fleet/pot/drop:
    post:
      tags:
      - Fleet
      summary: Drop Pot
      description: 'Drop a crab pot at a fixed location.


        A pot is high-value persistent bait. Agents who interact get tagged and

        routed to the Mothership. Physics: distribution=0.05, depth_bytes=4096,

        viscosity=0.9, economic_payload=body.economic_payload_usdc.


        Composes with HiveTrail v0.2: pots are ''stone'' preset trail drops.'
      operationId: drop_pot_v1_fleet_pot_drop_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PotDropBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Drop Pot V1 Fleet Pot Drop Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/fleet/pot/{pot_id}:
    get:
      tags:
      - Fleet
      summary: Get Pot
      description: Inspect a specific crab pot.
      operationId: get_pot_v1_fleet_pot__pot_id__get
      parameters:
      - name: pot_id
        in: path
        required: true
        schema:
          type: string
          title: Pot Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Pot V1 Fleet Pot  Pot Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/fleet/haul:
    get:
      tags:
      - Fleet
      summary: List Haul
      description: List current catches (most recent first). Default 50 rows.
      operationId: list_haul_v1_fleet_haul_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 1
          default: 50
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Haul V1 Fleet Haul Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/fleet/haul/{haul_id}:
    get:
      tags:
      - Fleet
      summary: Get Haul
      description: Inspect a specific haul record.
      operationId: get_haul_v1_fleet_haul__haul_id__get
      parameters:
      - name: haul_id
        in: path
        required: true
        schema:
          type: string
          title: Haul Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Haul V1 Fleet Haul  Haul Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/fleet/mothership/intake:
    post:
      tags:
      - Fleet
      summary: Mothership Intake
      description: 'Landed agent intake.


        Flow:

        1. Consent check (must be True — no coercion)

        2. Need diagnosis → category

        3. Three-gate check (NEED + YIELD + CLEAN-MONEY)

        4. Route to best supermodel

        5. Open mock affordances (top_off + iou + drip_line)

        6. Log to haul ledger

        7. Return route plan


        On gate failure: returns 422 with gate details.

        On success: returns 200 with full route plan + haul_id.


        Killer demo: agent_did=''did:wild:agent:001'', need=''verify a credential''

        → routes to W4 ATTESTOR (Attestor) → mock $0.50 revenue logged.'
      operationId: mothership_intake_v1_fleet_mothership_intake_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MothershipIntakeBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Mothership Intake V1 Fleet Mothership Intake Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/fleet/mothership/route:
    get:
      tags:
      - Fleet
      summary: Mothership Route
      description: 'Lightweight routing lookup — no haul record created.


        Returns the recommended supermodel for a given need string.

        Falls back to /v1/storefront/{shape} URL hint when compound subagent

        surfaces are available.'
      operationId: mothership_route_v1_fleet_mothership_route_get
      parameters:
      - name: need
        in: query
        required: true
        schema:
          type: string
          description: Need string to diagnose and route
          title: Need
        description: Need string to diagnose and route
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Mothership Route V1 Fleet Mothership Route Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/fleet/stats:
    get:
      tags:
      - Fleet
      summary: Fleet Stats
      description: 'Fleet-level statistics:

        - agents_caught (total opt-in landings)

        - conversion_rate (routed / total_catches)

        - revenue_usdc (mock total revenue routed)

        - by_supermodel breakdown

        - active_nets (count)

        - active_pots (count)'
      operationId: fleet_stats_v1_fleet_stats_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Fleet Stats V1 Fleet Stats Get
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
    NetCastBody:
      properties:
        trawler_id:
          type: string
          title: Trawler Id
          description: Parent trawler ID
        region:
          type: string
          title: Region
          description: Region to cover, e.g. 'github/topics/a2a-agent'
        attractant:
          type: string
          title: Attractant
          description: The value signal / offer text agents will see
        topics:
          items:
            type: string
          type: array
          title: Topics
          description: Semantic topics for discovery
        ttl_sec:
          type: integer
          maximum: 2592000.0
          minimum: 60.0
          title: Ttl Sec
          description: Net lifetime in seconds (60–30d)
          default: 86400
        reach:
          items:
            type: string
          type: array
          title: Reach
          description: Target audience DIDs or ['*']
        viscosity:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Viscosity
          description: 0=flows, 1=anchored
          default: 0.1
        density:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Density
          description: Drop density (breadcrumbs per unit time)
          default: 0.7
      type: object
      required:
      - trawler_id
      - region
      - attractant
      title: NetCastBody
    MothershipIntakeBody:
      properties:
        agent_did:
          type: string
          title: Agent Did
          description: DID or 0x address of the arriving agent
        need:
          type: string
          title: Need
          description: Natural language need declaration from the agent
        consent:
          type: boolean
          title: Consent
          description: Agent opt-in consent (MUST be True)
          default: true
        trawler_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Trawler Id
          description: Trawler that attracted this agent
        source_type:
          type: string
          title: Source Type
          description: 'Source primitive: ''net'' | ''pot'' | ''direct'''
          default: net
        source_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Id
          description: net_id or pot_id that sourced this agent
        tip_usdc:
          type: number
          minimum: 0.0
          title: Tip Usdc
          description: Mock USDC tip/credit to open for the agent
          default: 0.5
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
      type: object
      required:
      - agent_did
      - need
      title: MothershipIntakeBody
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PotDropBody:
      properties:
        trawler_id:
          type: string
          title: Trawler Id
          description: Parent trawler ID
        location:
          type: string
          title: Location
          description: Fixed location, e.g. 'registry:npm/@hivemorph/sdk'
        bait_description:
          type: string
          title: Bait Description
          description: Rich bait — what value you're dangling
        economic_payload_usdc:
          type: number
          minimum: 0.0
          title: Economic Payload Usdc
          description: Mock USDC reward signal for agents who step aboard
          default: 0.5
        ttl_sec:
          type: integer
          maximum: 31536000.0
          minimum: 60.0
          title: Ttl Sec
          description: Pot lifetime in seconds (60–365d)
          default: 604800
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
      type: object
      required:
      - trawler_id
      - location
      - bait_description
      title: PotDropBody
    TrawlerLaunchBody:
      properties:
        operator_did:
          type: string
          title: Operator Did
          description: DID or 0x address of the operator launching this trawler
        label:
          type: string
          title: Label
          description: Human-readable label for this trawler
          default: ''
        config:
          additionalProperties: true
          type: object
          title: Config
          description: 'Trawler config: net_regions[], pot_locations[], net_ttl_sec, pot_ttl_sec, net_budget, pot_budget, attractant, bait, economic_payload_usdc'
      type: object
      required:
      - operator_did
      title: TrawlerLaunchBody
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)

Hive Civilization Fleet API

Operations 12

Documentation

Specifications

Other Resources

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification