Call an API in a flow

#Goal

A flow that takes a topic, searches the public Hacker News API, and either has an agent summarise the stories or posts Nothing found.

#Prerequisites

• One agent with a working runtime.
• A channel for the "nothing found" message.
• Network access to hn.algolia.com.

#1. Create a blank flow

Flows → New flow → Blank flow, name it HN search, Create and open.

#2. Add the HTTP request

1. From Logic, add HTTP request and connect Start to it. Name it search. Its id (such as http-1) stays the same and is what placeholders use.
2. Method: GET. URL: https://hn.algolia.com/api/v1/search
3. Query parameters: + Add query, then press { } and choose Start → Run input. It inserts {{start.text}}. Add hitsPerPage = 5.

Behind the scenes: the value is URL-encoded when inserted, so it cannot change the host or path.

#3. Test and keep values

1. Under Test request, enter a sample for Start → text, such as rust.
2. Press Send test request.
3. In the response tree, click Keep on nbHits and on hits.

Expected: Values to keep now lists nbHits and hits, each taken from the body.

#4. Branch on the result

1. Add a Condition, connected from the HTTP step.
2. Rule: step search, a JSON field values.nbHits, is greater than, 0.
3. From Yes, add your agent. Task: Summarise these Hacker News stories in five bullet points with their titles. Under Give it the output of, tick the HTTP step.
4. From No, add Send message. Post to: your channel. Message: Nothing found for {{start.text}}.

#5. Run it

Save, then Run with input rust.

Expected: search completes, the condition takes Yes, the No path is skipped (dimmed), and the agent's summary is the run's output. Run again with a nonsense word to see the No path post its message.

Behind the scenes: the agent sees the kept values first, then the full response, fenced as untrusted data.

#6. See the safety rules

Change the URL to http://localhost:1/. The step reports uses unencrypted http://. Turning on Allow unencrypted http:// is not enough: running it then reports localhost resolves to a private address (127.0.0.1). Allow private network addresses in this step to call it. Put the URL back.

#Common mistakes

• Putting a placeholder in the host. The host must be written out: values from earlier steps may only go in the path or query.
• Keeping a key with a hyphen, such as user-name. Keep its parent instead.
• Forgetting to tick the HTTP step as the agent's input: the agent then sees nothing from it.

#Next steps

• HTTP requests
• Passing data