Building Your First Piece

What is a Piece?

A Piece is a self-contained Deno HTTP service that performs one specific action — query a database, send a Slack message, generate an embedding. The AI writes it, deploys it, and reuses it across workflows.

The Scaffold

Every piece follows the same structure:

typescript
import { serve } from "https://deno.land/std@0.224.0/http/server.ts";

serve(async (req: Request) => {
  const payload = await req.json();
  // your logic here
  return new Response(JSON.stringify({ ok: true }), {
    headers: { "content-type": "application/json" },
  });
}, { port: 8080 });

The serve function from Deno's standard library starts an HTTP server on port 8080. Your piece receives a request, does work, and returns a response.

Adding Configuration

Use environment variables for configuration. OpenPieces injects these automatically when your piece is deployed:

typescript
const API_KEY = Deno.env.get("MY_API_KEY")!;
const ENDPOINT = Deno.env.get("MY_ENDPOINT")!;

Testing Locally

Before publishing, test your piece locally:

bash
deno run --allow-net --allow-env my-piece.ts

Then send a test payload with curl:

bash
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

Publishing to the Marketplace

Once tested, submit your piece to the marketplace. The AI quality scorer evaluates your code for:

• Error handling coverage
• Type safety
• Input validation
• Documentation clarity

A score above 85 is considered production-ready.

Next Steps

Try building a piece that connects to your favourite API. The pattern is always the same: receive, transform, respond. The marketplace is waiting.