Ikiro Developer Docs

Operations are the building blocks of superpowers. Each operation runs sequentially within an action. Results from one operation are available to the next via {{$vars.output_name}}.

AI Operations

llm_generate

Generate free-form text using an LLM.

- type: llm_generate
  output: summary
  prompt: "Summarize this: {{$input.text}}"

llm_extract

Extract structured data from text.

- type: llm_extract
  output: city
  input: "{{$input.text}}"
  output_schema:
    type: object
    properties:
      name:
        type: string
        description: "City name"

vision_analysis

Analyze images with Gemini Vision.

- type: vision_analysis
  output: analysis
  prompt: "Describe what's in this image"
  input_images: "{{$input.images}}"

Integration Operations

http_request

Call external REST APIs. Domain must be on the allowlist.

- type: http_request
  output: weather
  method: GET
  url: "https://api.openweathermap.org/data/2.5/weather?q={{$state.city}}&units=imperial"
  platform_key_ref: openweathermap  # Ikiro provides the API key
  response_path: main               # Extract nested JSON field

Auth options:

platform_key_ref — Ikiro-owned API key (free for listed integrations)
auth_token_ref — User's OAuth token (gmail, calendar, strava, etc.)
Manual headers.Authorization — Your own API key

gmail_search

Search the user's Gmail. Requires oauth_required: [gmail].

- type: gmail_search
  output: emails
  query: "is:unread from:{{$state.sender}}"
  max_results: 5

calendar_query

Query Google Calendar. Requires oauth_required: [calendar].

- type: calendar_query
  output: events
  query:
    time_min: "{{$today.start}}"
    time_max: "{{$today.end}}"
    order_by: startTime
    single_events: true

web_search

Search the web.

- type: web_search
  output: results
  query: "{{$input.text}}"
  max_results: 10

memory_read

Search the user's memories.

- type: memory_read
  output: memories
  query: "user's favorite restaurants"

memory_write

Store a memory for the user.

- type: memory_write
  memory_type: factual
  content: "User logged a run: {{$vars.distance}}km"
  tags: [fitness, running]

Data Operations

state_update

Update session state.

- type: state_update
  data:
    count: "{{$state.count + 1}}"
    last_checked: "{{$now.iso}}"

calculate

Safe math operations (no eval).

- type: calculate
  output: per_person
  expression: "{{$state.total}} / {{$vars.num_people}}"
  round_to: 2

Supports: +, -, *, /, %, **, round(), ceil(), floor(), min(), max(), sum(), len(), abs()

build_url

Construct URLs with encoded parameters.

- type: build_url
  output: payment_url
  base_url: "https://venmo.com/pay"
  params:
    amount: "{{$vars.per_person}}"
    note: "{{$state.merchant}}"
  url_encode: true

emit_event

Emit a single event to the event store (event sourcing pattern).

- type: emit_event
  event_type: item_added
  payload:
    name: "{{$input.text}}"
  output: result

Flow Control

conditional

If/then/else branching.

- type: conditional
  condition: "{{$state.total}} > 50"
  then:
    - type: state_update
      data: { discount: 10 }
  else:
    - type: state_update
      data: { discount: 0 }

loop

Iterate over a collection (max 100 iterations).

- type: loop
  items: "{{$state.participants}}"
  operation:
    type: send_message
    recipient: "{{$loop.item.phone}}"
    message: "Your share: {{$loop.item.amount}}"

conversation_flow

Ask the user a question and pause execution until they respond.

- type: conversation_flow
  output: user_input
  prompt: "How many people?"
  options: ["2", "3", "4", "5+"]
  timeout_seconds: 120
  default_on_timeout: "2"

Communication

send_message

Send a DM to another user (max 5 per action).

- type: send_message
  recipient: "{{$state.participants[0].phone}}"
  message: "You owe {{$vars.per_person}}"

notify

Send a proactive notification.

- type: notify
  message: "{{$vars.alert_message}}"

Scheduling

schedule

Schedule delayed or recurring execution.

# One-time delay
- type: schedule
  mode: once
  delay_hours: 24
  action_id: send_reminder

# Recurring cron
- type: schedule
  mode: recurring
  cron: "0 9 * * *"    # 9 AM daily
  action_id: daily_digest

Recurring schedules require a paid plan. See billing for limits.

schedule_task

Schedule a future action with context.

- type: schedule_task
  delay_hours: 24
  action_id: send_reminder
  context:
    merchant: "{{$state.merchant}}"
  max_retries: 2

Document

generate_document

Generate a document via the Document Service.

- type: generate_document
  document_type: essay
  document_title: "Weekly Report"
  document_prompt: "Generate a report based on: {{$state.activities}}"

Operations Reference