Neynar Documentation

The Miniapp Studio API is an allowlisted API and not publicly available. Contact the Neynar team for more information.

This tutorial demonstrates how to use the Miniapp Studio API to create and manage Farcaster miniapp generator deployments programmatically. You’ll learn how to create deployments, send prompts for code generation, manage multiple deployments, and clean up resources.

Prerequisites

An allowlisted Neynar API key
Your Farcaster ID (FID)

API Endpoints Overview

The Miniapp Studio API provides the following endpoints for managing deployments:

Create Deployment: POST /v2/studio/deployment/ - Create a new miniapp generator deployment
Get Deployment: GET /v2/studio/deployment/by-name-and-fid - Fetch deployment details
List Deployments: GET /v2/studio/deployment/ - List all deployments for a user
Prompt Deployment: POST /v2/studio/deployment/prompt - Send a prompt to generate code
Stream Prompt: POST /v2/studio/deployment/prompt/stream - Send a prompt and stream AI responses in real-time
Associate Account: POST /v2/studio/deployment/account-association - Link a generated app to Farcaster account
Delete Deployment: DELETE /v2/studio/deployment/ - Remove deployments

Step 1: Create a Deployment

Start by creating a new deployment for your Farcaster account using the Create Deployment endpoint:

curl https://api.neynar.com/v2/studio/deployment \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "fid": YOUR_FID
  }'

Response:

{
  "created_at": "2025-09-04T16:24:35.185Z",
  "namespace": "miniapp-generator-fid-1568",
  "name": "server-250904162435170",
  "isReady": false
}

Save the name field from the response - you’ll need it to interact with this deployment.

You can create multiple deployments per FID, as each FID-name combination refers to a single deployment.

Step 2: Check Deployment Readiness

After creating a deployment, it may take up to a minute to become ready. You should poll the Get Deployment endpoint until isReady is true:

curl "https://api.neynar.com/v2/studio/deployment/by-name-and-fid?name=server-250904162435170&fid=YOUR_FID" \
  -H "x-api-key: YOUR_API_KEY"

Response (when ready):

{
  "created_at": "2025-09-04T16:24:35.185Z",
  "namespace": "miniapp-generator-fid-1568",
  "name": "server-250904162435170",
  "isReady": true,
  "url": "https://server-250904162435170.studio.neynar.com"
}

Step 3: Prompt the Deployment for Code Generation

Once your deployment shows isReady: true, you can send prompts to generate miniapp code. Since generation can take 5-10 minutes, the streaming option is recommended for better user experience.

Option A: Streaming Prompt (Recommended)

The Stream Prompt endpoint provides real-time progress updates using Server-Sent Events (SSE):

curl https://api.neynar.com/v2/studio/deployment/prompt/stream \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "fid": YOUR_FID,
    "name": "server-250904162435170",
    "prompt": "generate a mini app that lets any user edit the main page headline, with orange and blue theme",
    "action": "code-create"
  }'

Streaming Response Example:

data: {"type":"connection","message":"Streaming started"}
data: {"type":"system","subtype":"init","message":"Initializing..."}
data: {"type":"assistant","message":"Creating your miniapp..."}
data: {"type":"result","subtype":"success","message":"Deployment complete"}

The streaming endpoint returns various message types:

SDKAssistantMessage: Claude’s responses during generation
SDKUserMessage: User prompts being processed
SDKResultMessage: Final results (success/error)
SDKSystemMessage: System initialization messages
ErrorMessage: Any errors during generation

All message types are exported by the @anthropic-ai/claude-code npm package except the ErrorMessage type, which simply consists of type: "error", an error message, and a timestamp.

Option B: Standard REST API (Wait for Complete Response)

The Prompt Deployment endpoint will wait until generation is complete before returning a response:

curl https://api.neynar.com/v2/studio/deployment/prompt \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "fid": YOUR_FID,
    "name": "server-250904162435170",
    "prompt": "generate a mini app that lets any user edit the main page headline, with orange and blue theme",
    "action": "code-create"
  }'

This endpoint will wait 5-10 minutes until generation completes before returning a response. Use the streaming endpoint for real-time progress updates.

Action Types for Prompt Operations

Both prompt endpoints support an optional action parameter that specifies the type of operation to perform on your deployment:

code-create (default): Generate new code for a fresh project. Use this when starting a new miniapp from scratch.
code-edit: Make edits to an existing project that has already been prompted at least once. Use this for modifying or adding features to your miniapp.
debug: Debug issues with your generated miniapp. The AI will analyze your code and help identify and fix problems.
info: Get information about your generated miniapp.
logs: Query the latest server logs for further debugging. This helps you understand runtime issues and errors for manual debugging.

Example with action parameter:

curl https://api.neynar.com/v2/studio/deployment/prompt \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "fid": YOUR_FID,
    "name": "server-250904162435170",
    "prompt": "add a user authentication feature",
    "action": "code-edit"
  }'

Step 4: Associate Deployment with Account

Link your deployment to your Farcaster account with JFS using the Associate Account endpoint:

curl https://api.neynar.com/v2/studio/deployment/account-association \
  -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "fid": YOUR_FID,
    "name": "server-250904162435170",
    "domain": "your-miniapp.example.com",
    "signature": "JFS_SIGNATURE_HERE"
  }'

The JFS (JSON Farcaster Signature) object is required for domain association. This verifies that you own both the Farcaster account and the domain.

🎉 Your miniapp should now be fully functional! You can access it at the URL returned in Step 2.

Additional API Actions

Beyond the core deployment workflow, you can use these endpoints to manage your deployments:

List All Deployments

View all deployments associated with your FID using the List Deployments endpoint:

curl "https://api.neynar.com/v2/studio/deployment?fid=YOUR_FID" \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "deployments": [
    {
      "name": "server-250904162435170",
      "display_name": "tetris app",
      "created_at": "2025-09-04T16:24:35.185Z",
      "isReady": true
    },
    {
      "name": "server-250904173546281",
      "created_at": "2025-09-04T17:35:46.281Z",
      "isReady": false
    }
  ]
}

Clean Up Deployments

You can delete deployments in two ways using the Delete Deployment endpoint:

Delete a Specific Deployment

curl https://api.neynar.com/v2/studio/deployment \
  -X DELETE \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "fid": YOUR_FID,
    "name": "server-250904162435170"
  }'

Delete All Deployments for Your FID

curl https://api.neynar.com/v2/studio/deployment \
  -X DELETE \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "fid": YOUR_FID
  }'

Deleting all deployments will remove every deployment associated with your FID. This action cannot be undone.

Best Practices

Always save deployment names: Store the deployment name from the creation response to interact with it later
Use streaming for long operations: The streaming endpoint provides better user experience for prompt operations
Clean up unused deployments: Regularly delete deployments you’re no longer using to keep your account organized

Troubleshooting

Deployment Not Ready

If isReady is false, wait a few moments before trying to prompt the deployment. New deployments need time to initialize.

Streaming Connection Issues

For streaming endpoints, ensure your HTTP client supports Server-Sent Events (SSE). Most modern libraries and tools support this natively.

Next Steps

Explore the Mini App Authentication to add user sign-in to your generated miniapps
Learn about Sending Notifications to engage users
Check out the Neynar Starter Kit for building miniapps from templates

If you have questions or need help, reach out to the Neynar team.

Get Started

Fetch User Information

Build Farcaster Mini Apps

Host Farcaster Mini Apps

Fetch Cast Information

Build Bots and Agents

Fetch Farcaster Feeds

Onboard New Users

Write Data to Farcaster

Filter Spam, Low Quality Data

Run Queries on FC Data

Render Farcaster in React

Get Events Via Webhooks

Fetch Notifications

Create Onchain Transactions

Intersect Onchain & Social Data

Write Direct Casts

Get Farcaster Storage Data

Publish Actions on FC Apps

Get Farcaster Data on Base

Explore Network Health

Get Hypersub Subscriptions

Contribute To Development

​Prerequisites

​API Endpoints Overview

​Step 1: Create a Deployment

​Step 2: Check Deployment Readiness

​Step 3: Prompt the Deployment for Code Generation

​Option A: Streaming Prompt (Recommended)

​Option B: Standard REST API (Wait for Complete Response)

​Action Types for Prompt Operations

​Step 4: Associate Deployment with Account

​Additional API Actions

​List All Deployments

​Clean Up Deployments

​Delete a Specific Deployment

​Delete All Deployments for Your FID

​Best Practices

​Troubleshooting

​Deployment Not Ready

​Streaming Connection Issues

​Next Steps

Prerequisites

API Endpoints Overview

Step 1: Create a Deployment

Step 2: Check Deployment Readiness

Step 3: Prompt the Deployment for Code Generation

Option A: Streaming Prompt (Recommended)

Option B: Standard REST API (Wait for Complete Response)

Action Types for Prompt Operations

Step 4: Associate Deployment with Account

Additional API Actions

List All Deployments

Clean Up Deployments

Delete a Specific Deployment

Delete All Deployments for Your FID

Best Practices

Troubleshooting

Deployment Not Ready

Streaming Connection Issues

Next Steps