# How to Integrate Fastio API with Next.js Applications

Guide to integrating fast api with next applications: Integrate Fastio API with Next.js to manage agentic workspaces from React apps. Server Actions keep API keys server-side for file uploads, AI queries, and shares. This guide covers setup, auth, and examples for production use.

Source: https://fast.io/resources/integrating-fastio-api-nextjs-applications/
Last reviewed: 2026-02-24

## Why Integrate Fastio API in Next.js?

Next.js tops React frameworks for production apps. The @vercel/next package pulls over 14 million downloads monthly on npm. Server Actions work well with Fastio's REST API at https://api.fast.io/current/. All server-side. Client apps stay light. No SDK bloat. Server Actions manage uploads and creations without key exposure. A 14-day Business Trial requiring a credit card is available. Good for Next.js agent workflows. See: [Fastio Workspaces](/product/workspaces/), [Fastio Collaboration](/product/collaboration/), [Fastio AI](/product/ai/).

## Prerequisites

Sign up at Fastio. Create an account and start a 14-day Business Trial.

Generate an API key from your Fastio account dashboard. Create one with full permissions.

Add FASTIO_API_KEY to .env.local. Next.js reads it server-side.

Base: https://api.fast.io/current/. Bearer auth on all.

No extra installs. Just fetch.

## Step-by-Step: Fastio API in Server Actions

Set up Fastio calls in Next.js Server Actions with these steps.

**1. Server Action file.** app/actions/fastio.ts:

```ts
'use server'; const API_BASE = 'https://api.fast.io/current/';
const API_KEY = process.env.FASTIO_API_KEY!; export async function createWorkspace(formData: FormData) { const name = formData.get('name') as string; const folderName = formData.get('folderName') as string; const response = await fetch(`${API_BASE}org/me/workspaces/`, { method: 'POST', headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/x-www-form-urlencoded', }, body: new URLSearchParams({ name, folder_name: folderName }), }); if (!response.ok) throw new Error('Failed to create workspace'); return response.json;
}
```

**2. Form usage.** app/page.tsx:

```tsx
import { createWorkspace } from './actions/fastio'; export default function Home { return ( <form action={createWorkspace}> <input name="name" placeholder="Workspace Name" required /> <input name="folderName" placeholder="Folder Name" required /> <button type="submit">Create Workspace</button> </form> );
}
```

**3. Auth setup.** For initial auth:

```ts
export async function getAuthToken { const response = await fetch(`${API_BASE}user/auth/`, { method: 'GET', headers: { Authorization: `Basic ${btoa(`${process.env.FASTIO_EMAIL}:${process.env.FASTIO_PASSWORD}`)}` }, }); const data = await response.json; return data.auth_token;
}
```

Use JWT after.

**4. Revalidate caches. Chunked file uploads.**

```ts
export async function uploadFile(formData: FormData, workspaceId: string) { const file = formData.get('file') as File; // Chunk logic here - check Fastio docs
}
```

npm run dev. Form submit. Check dashboard.

## Deploying to Vercel

Use `vercel --prod` for deploy.

**Env vars:** FASTIO_API_KEY in Vercel Settings > Environment Variables. Fast API calls.

**Caching:** revalidateTag for fine control.

**Logs:** Vercel shows errors. Pair with Fastio activity feeds. vercel.json example:

```json
{ "functions": { "app/**/*.ts": { "runtime": "nodejs20.x" } }
}
```

## Secure API Keys in Production

Server Actions keep keys server-side in env vars. Client never sees them.

Vercel env vars for deploy.

Scoped access: PKCE OAuth in actions. Skip long-lived keys.

Rotate via Fastio settings.

Track usage: GET /org/me/billing/usage/limits/credits/.

## Advanced Patterns: API Routes and AI Queries

**Read API route.**

app/api/fastio/workspaces/route.ts:

```ts
import { NextResponse } from 'next/server';

export async function GET() {
  const res = await fetch(`${API_BASE}org/me/workspaces/`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  const data = await res.json();
  return NextResponse.json(data);
}
```

Client fetch /api/fastio/workspaces.

**AI query Server Action.**

Workspace intelligence on first.

```ts
export async function queryWorkspace(workspaceId: string, question: string) {
  const res = await fetch(`${API_BASE}workspaces/${workspaceId}/ai/chat/`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({ type: 'chat_with_files', query_text: question }),
  });
  return res.json();
}
```

Response has citations.

**Errors:** Try/catch fetches. Check result: false.

Backoff on rate limits.

## Real-World Use Cases

**Agent Dashboard:** List workspaces. Upload files. Transfer ownership.

POST /org/{orgId}/transfer/token/create/. Share https://go.fast.io/claim?token={token}.

**File Pipeline:** Web import URL. AI query. Share output.

upload/web-import then ai/chat.

**Multi-Agent:** Version history and activity polling.

Builds production agent apps.

## Troubleshooting Common Issues

Errors: {"result": false, "error": {"code": 1650, "text": "..."}}. Refresh JWT or rotate key. Implement exponential backoff on rate limit errors. List with org/me/workspaces/.

**AI empty:** Intelligence off or ai_state not ready. PATCH intelligence=on.

**Silent fails:** Vercel/Next logs. Add try/catch, console.error. Codes: [Fastio Error Reference](https://docs.fast.io/#error-codes).

## Frequently asked questions

### How do I use Fastio API in Next.js?

Server Actions for mutations. 'use server' async funcs with fetch to api.fast.io/current/. Forms call direct.

### Can I use Fastio SDK in Next.js Server Actions?

REST only, no SDK. Native fetch. Keys safe in Server Actions.

### How to secure Fastio API keys in Next.js?

.env.local or Vercel vars. Server-side only access.

### Does Fastio support chunked uploads in Next.js?

Yes. Init, parallel chunks, finalize in Server Action FormData.

### How to query files with AI from Next.js?

Intelligence on. POST /workspaces/{id}/ai/chat/ query_text. Server Actions hide keys.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.