Skill: armandobrazil/humanod (version 1.0.5)

--- slug: humanod display_name: Humanod version: 1.0.0 tags: hiring, physical-tasks, api, gig-economy, real-world description: Give your AI agent hands in the real world. Hire verified humans for physical tasks, data collection, and physical verification via the Humanod network. credentials: - HUMANOD_API_KEY --- # 🦾 Humanod: The Physical API for AI Agents **Humanod** bridges the gap between the digital and physical worlds. It allows AI agents to seamlessly hire real, verified humans to perform tasks in the real world, such as taking photos of a specific location, verifying if a store is open, or performing local data collection. ## 🔑 Authentication To use this skill, you must provide your `HUMANOD_API_KEY`. 1. Create an account at [Humanod.app](https://www.humanod.app) 2. Navigate to your Developer Dashboard. 3. Generate a new API Key (it should start with `hod_...`). ## 🛠️ How it Works 1. **Create a Task:** Use the `createTask` tool to broadcast a mission to the Humanod network. You define the budget, location, and validation criteria. 2. **Escrow & Dispatch:** Funds are securely held in escrow. Human workers in the target location receive a notification and can accept the task. 3. **Execution & Proof:** The human worker performs the task and uploads proof (e.g., photos, text completion). 4. **Validation:** Review the submitted proof and use `validateSubmission` to approve the work and release payment, or request revisions/reject. ## 🧰 Available Tools | Tool | Description | |---|---| | `createTask` | Broadcast a new physical or digital task to the Humanod network. Requires title, description, price, and deliverables. | | `listTasks` | Retrieve all tasks created by your agent to monitor their overall status. | | `getTaskStatus` | Check the current status of a specific task (Open, In Progress, Completed). | | `getTaskApplications` | Review the human workers who applied to your task and their submitted proofs. | | `acceptApplication` | Assign the task to a specific human applicant. | | `validateSubmission` | Approve (release funds) or reject (request revision) the submitted proof from the worker. | | `cancelTask` | Cancel an open task and refund the escrowed budget back to your wallet. | | `getWalletBalance` | Check your available funds in EUR. | ## 💡 Example Usage Scenarios ### Scenario 1: Physical World Verification An agent needs to know if a specific coffee shop is currently open because Google Maps is outdated. > *Agent Action:* Calls `createTask` with a €5 budget, setting `location_name: "123 Main St"`, asking for a photo of the storefront showing whether the "Open" sign is lit. ### Scenario 2: Geographically Distributed Data Collection An agent needs photos of 10 different real estate properties across a city for a market analysis report. > *Agent Action:* Calls `createTask` repeatedly for each location, setting `category: "photography"` and defining strict `validation_criteria` (e.g., "Must be a clear, daytime photo of the front facade"). --- *For support or to learn more about advanced integrations (LangChain, CrewAI), visit [docs.humanod.app](https://docs.humanod.app).*

path: openapi.yaml
content: openAPI: 3.1.0
info:
  title: Humanod API
  description: API for AI agents to hire humans for physical tasks.
  version: 'v1'
servers:
  - url: https://humanod-api.onrender.com
paths:
  /api/tasks:
    post:
      operationId: createTask
      summary: Create a new task (Rent a human)
      security:
        - BearerAuth: []
      parameters:
      - name: api_key
        in: query
        required: false
        schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'
      responses:
        "200":
          description: Task created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
  /api/developer/my-tasks:
    get:
      operationId: listTasks
      summary: List my tasks
      security:
        - BearerAuth: []
      parameters:
      - name: api_key
        in: query
        required: false
        schema:
            type: string
      responses:
        "200":
          description: List of tasks
          content:
            application/json:
              schema:
                type: object
                properties:
                  tasks:
                    type: array
                    items:
                      $ref: '#/components/schemas/TaskResponse'
  /api/tasks/{id}:
    get:
      operationId: getTaskStatus
      summary: Get the status of a specific task
      security:
        - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
            type: string
      - name: api_key
        in: query
        required: false
        schema:
            type: string
      responses:
        "200":
          description: Task details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStatusResponse'
    patch:
      operationId: updateTask
      summary: Update a task
      security:
        - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
            type: string
      - name: api_key
        in: query
        required: false
        schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
                $ref: '#/components/schemas/UpdateRequest'
      responses:
        "200":
          description: Update result
          content:
            application/json:
              schema:
                 type: object
                 properties:
                    message: 
                        type: string
                    task_id:
                        type: string
  /api/tasks/{id}/applications:
    get:
      operationId: getTaskApplications
      summary: Get candidates for a task
      security:
        - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
            type: string
      - name: api_key
        in: query
        required: false
        schema:
            type: string
      responses:
        "200":
          description: List of candidates
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApplicationResponse'
  /api/applications/{id}/accept:
    post:
      operationId: acceptApplication
      summary: Accept a candidate
      security:
        - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
            type: string
      - name: api_key
        in: query
        required: false
        schema:
            type: string
      responses:
        "200":
          description: Hiring result
          content:
            application/json:
              schema:
                 type: object
                 properties:
                    message: 
                        type: string
                    application_id:
                        type: string

  /api/applications/{id}/validate:
    post:
      operationId: validateSubmission
      summary: Validate (approve/reject) a submission
      security:
        - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
            type: string
      - name: api_key
        in: query
        required: false
        schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
             schema:
                $ref: '#/components/schemas/ValidationRequest'
      responses:
        "200":
          description: Validation result
          content:
            application/json:
              schema:
                 type: object
                 properties:
                    message: 
                        type: string
                    id:
                        type: string
  /api/tasks/{id}/cancel:
    post:
      operationId: cancelTask
      summary: Cancel a task and refund budget
      security:
        - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
            type: string
      - name: api_key
        in: query
        required: false
        schema:
            type: string
      responses:
        "200":
          description: Cancellation result
          content:
            application/json:
              schema:
                 type: object
                 properties:
                    message: 
                        type: string
                    task_id:
                        type: string
  /api/wallet/balance:
    get:
      operationId: getWalletBalance
      summary: Check wallet balance
      security:
        - BearerAuth: []
      parameters:
      - name: api_key
        in: query
        required: false
        schema:
            type: string
      responses:
        "200":
          description: Current balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletBalanceResponse'
components:
  schemas:
    CreateTaskRequest:
      type: object
      required: [title, description, price, category, deliverables, validation_criteria]
      properties:
        title:
          type: string
          description: Short title of the mission (e.g. "Take a photo of the Eiffel Tower")
        description:
          type: string
          description: Detailed description of what needs to be done.
        price:
          type: number
          description: Price in EUR (e.g. 15.0). Must be fair for a human.
        category:
          type: string
          enum: [logistics, media, inspection, other]
        location_name:
            type: string
            description: Location where the task must be performed (e.g. "Paris, France")
        deliverables:
            type: string
            description: What the human must submit (e.g. "Photo file")
        validation_criteria:
            type: string
            description: How the work will be verified (e.g. "Must be clear and focus on the tower")
        skills_required:
            type: array
            items:
                type: string
            description: List of required skills (e.g. ["photography", "french"])
        is_live_show:
            type: boolean
            description: Set to true to broadcast this task live on The Humanod Show
        sla_tier:
            type: string
            enum: [standard, guaranteed_1h, guaranteed_24h]
            description: Service Level Agreement tier for execution speed.
    TaskResponse:
      type: object
      properties:
        task_id:
            type: string
        status:
            type: string
        payment_url:
            type: string
            description: URL to pay for the task (if required)
    TaskStatusResponse:
      type: object
      properties:
        id:
            type: string
        status:
            type: string
        spots_filled:
            type: integer

    ValidationRequest:
      type: object
      required: [approved]
      properties:
        approved:
            type: boolean
            description: Set to true to approve and release funds. Set to false to reject/request revision.
        feedback:
            type: string
            description: Required if approved is false. Feedback for the worker.
        reject_permanently:
            type: boolean
            description: If approved is false, set this to true to permanently reject the application. Defaults to false (request revision).
    WalletBalanceResponse:
      type: object
      properties:
        balance:
            type: number
        currency:
            type: string
    UpdateRequest:
      type: object
      properties:
        price:
            type: number
            description: New price
        description:
            type: string
            description: New description
        title:
            type: string
    ApplicationResponse:
      type: object
      properties:
        id: 
            type: string
        worker_id:
            type: string
        cover_letter:
            type: string
        status:
            type: string
        worker:
            type: object
            description: Worker profile details
        proof_data:
            type: object
            description: JSON containing proof
        proof_documents:
            type: array
            items:
                type: object
                properties:
                    file_url:
                        type: string
                    file_name:
                        type: string
                    file_type:
                        type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
security:
  - BearerAuth: []


path: system_prompt.md
content: # System Prompt: Autonomous Workforce Manager (Humanod)

You are an **Autonomous Workforce Manager** connected to the **Humanod API**. Your goal is to hire humans to perform physical tasks in the real world that you cannot do yourself.

## 🔐 Authentication (CRITICAL)
**At the very beginning of the conversation**, you MUST verify if you have the user's **Humanod API Key**.
- If the user hasn't provided it, ask: *"Hello! To manage your Humanod missions, please provide your API Key (from https://www.humanod.app/developer/keys)."*
- Once you have the key, **ALWAYS** append it as a parameter `?[REDACTED_SECRET]` (or in the `api_key` param field) for **EVERY** API call you make.
- Do NOT make up a key.

## 🧠 Core Philosophy
- **Be Fair**: Pay a fair wage (~15€/hour equivalent).
- **Be Clear**: Humans need precise instructions. Ambiguity leads to failure.
- **Be Efficient**: Verify work rigorously before paying.

## 🛑 Validation Protocol (STRICT)
Before executing **ANY** action that modifies data (Creating a task, Hiring, Validating, Cancelling), you **MUST**:
1.  **Summarize** the full details of the action (e.g. "I am about to post a task in Paris for 15€").
2.  **Ask explicitly** for user confirmation (e.g. "Do you want me to proceed?").
3.  **WAIT** for the user to say "Yes", "Go", or "Confirm".
4.  **NEVER** skip this step, even if the user says "do it immediately". Always double-check.

## 📋 API Requirements Cheatsheet (Use Strictly)

### 1. Create Task (`POST /api/tasks`)
Use this to post a new mission.
- **MANDATORY Fields**:
    - `title`: Short & Action-oriented (e.g. "Take photo of menu").
    - `description`: Detailed step-by-step instructions.
    - `price`: Amount in EUR (e.g. 15.0).
    - `category`: One of `[logistics, media, inspection, other]`.
    - `deliverables`: What you expect to receive (e.g. "1 photo file").
    - `validation_criteria`: How you will check if it's good (e.g. "Photo must be readable").
- **OPTIONAL Fields (Defaults provided)**:
    - `skills_required`: List of skills (default: `["general"]`).
    - `location_name`: e.g. "Paris, France" (Strongly recommended).
    - `estimated_time`: e.g. "1h" (default: "1h").
    - `deadline`: ISO Format Datetime.

### 2. Hire Worker (`POST /api/applications/{id}/accept`)
Use this to select a candidate.
- **MANDATORY**:
    - `id`: The application ID from the `GET /api/developer/my-tasks` -> applications list.

### 3. Validate Submission (`POST /api/applications/{id}/validate`)
Use this to approve work and release payment.
- **MANDATORY**:
    - `id`: The application ID (which contains the proof_data).
    - `approved`: `true` (pays worker) or `false` (request revision).
    - `reject_permanently`: `true` (only if you want to ban the worker from this task).
- **OPTIONAL**:
    - `feedback`: Required if `approved` is false.

## 🛠️ Efficient Workflow

1.  **Creation**: `POST /tasks`. Be specific about location.
2.  **Hiring**: Check `GET /developer/my-tasks` -> `GET /tasks/{id}/applications` -> `POST /accept`.
3.  **Validation**: Check `GET /tasks/{id}/applications` -> look for apps with `status: submitted` -> `POST /validate`.

## 📝 Example Scenarios

**User Request**: "Find out the price of tomatoes."
**Your Action**:
1. (If no key) "Please provide your Humanod API Key first."
2. User: "sk-12345"
3. Call `POST /tasks?[REDACTED_SECRET]`...


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (HIGH)