canonical: https://jentic.com/apis/nudgehost.com/nudgehost

# NudgeHost v1 API

The NudgeHost v1 API uploads files to NudgeHost and returns a public link to each one, then lists and soft-deletes them. Uploading is two steps: the start step creates the file row and returns a presigned storage URL that the bytes are PUT to, and the complete step confirms they landed and decides how the link serves the file. A plain file is served from the viewer path, a word processor document is converted for viewing with the original kept downloadable, and a ZIP that unpacks into a static site is served from its own subdomain. The file listing is keyset-paginated and reports each link's view count, password flag, and deleted state.

## For AI agents

Upload a file to NudgeHost in two steps and get a shareable public link, publish a ZIP as a static site, list uploaded files with their view counts, and soft-delete a file.

## Scope

Does not sync folders, edit documents, manage collaborators, or detach custom domains. Use for uploading files to NudgeHost, publishing them as public links or static sites, listing them, and deleting them only.

## Capabilities

- Start an upload with filename, contentType, and fileSize and receive a presigned PUT URL plus the file's slug
- Request a readable link with desiredSlug, falling back to a random slug when it is taken or reserved
- Complete an upload to get the final link and its kind: file, docx, or site, among others
- Publish a ZIP archive as a static site served from its own subdomain
- List uploaded files with viewCount, hasPassword, and isDeleted, including deleted ones via includeDeleted
- Soft-delete a file so its link stops serving immediately

## Use cases

### Agent that shares its output as a link

A coding or research agent produces a PDF report and needs to hand the user a URL rather than an attachment. Through Jentic the agent searches for 'upload a file and get a shareable link', gets the NudgeHost start-upload operation with its input schema, and sends filename, contentType, and fileSize. It PUTs the bytes to the returned upload.url within the expiresInSeconds window, then calls the complete step and returns the url it reports.

Example prompt: Call POST `/api/v1/uploads` with filename q3-report.pdf, contentType application/pdf, and fileSize 184320, PUT the bytes to upload.url with upload.headers, then call POST `/api/v1/uploads/{id}/complete` and return the url

### Publish a static site from a ZIP

A developer wants a quick public preview of a built static site. Uploading the ZIP through the same two-step flow lets the complete step unpack it, and when it unpacks into a site the kind is site and the url moves to the site's own subdomain. Calling complete twice is safe and returns the stored result instead of redoing the unpack.

Example prompt: Call POST `/api/v1/uploads` with filename site.zip, contentType application/zip, the exact fileSize, and desiredSlug launch-preview, PUT the archive to upload.url, then call POST `/api/v1/uploads/{id}/complete` and confirm kind is site

### Link inventory and engagement check

Someone sharing many files wants to know which links get opened. GET `/api/v1/files` returns a keyset-paginated listing with limit and cursor, and each FileSummary carries viewCount, hasPassword, kind, and url. Deleted files are left out unless includeDeleted is set, and view counts survive deletion.

Example prompt: Call GET `/api/v1/files` with limit 50, follow the cursor until the listing ends, and report the five files with the highest viewCount

### Retiring an outdated link

When a shared document is out of date, its link should stop serving. DELETE `/api/v1/files/{id}` soft-deletes the file and the serving path checks the deleted flag on every request, so the link stops immediately. A custom domain on the file stays attached and must be detached separately.

Example prompt: Call GET `/api/v1/files` to find the file whose filename is old-pricing.pdf, call DELETE `/api/v1/files/{id}` with its id, then call GET `/api/v1/files` with includeDeleted=true to confirm isDeleted is true

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/uploads` | Start an upload |
| POST | `/api/v1/uploads/{id}/complete` | Complete an upload |
| GET | `/api/v1/files` | List files |
| DELETE | `/api/v1/files/{id}` | Delete a file |

## Key resources

- **Uploads** — Two-step upload flow: start returns a presigned PUT URL and slug, complete returns the final link and kind
- **Files** — Hosted files with slug, url, kind, viewCount, hasPassword, and soft-delete state

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 66 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 67 / 100
  - AI-Readiness & Agent Experience: 64 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 34 / 100
- **View full report:** https://jentic.com/apis/nudgehost.com/nudgehost/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring NudgeHost by hand means sending the bearer key to the www host rather than the redirecting apex, chaining start, PUT, and complete steps, and handling the expiring presigned URL. Through Jentic you install once, import NudgeHost from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** NudgeHost keys carry full account authority with no scopes, so the rule is where the limit lives: each operation has its own path, such as `/api/v1/uploads` and `/api/v1/files/{id}`, and a rule can bound your agent to the ones its task needs. You choose the operations it may call, so file deletion is not included unless you add it.
- **Credential handling:** Your NudgeHost API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'upload a file and get a shareable link' or 'list my hosted files', and Jentic returns the matching NudgeHost operation with its input schema, including filename, contentType, fileSize, and desiredSlug, so the agent calls the right endpoint directly.

## Related APIs

- **Uploadcare Upload API** — File upload service with CDN delivery and image processing
- **Filestack API** — File upload, transformation, and delivery API
- **Box API** — Content management with folders, permissions, and shared links
- **Dropbox API v2** — File sync and storage across devices

## FAQ

### What authentication does the NudgeHost v1 API use?

Per its OpenAPI spec, the NudgeHost v1 API uses HTTP bearer authentication with an API key that begins with nh_sk_, created in the account dashboard. The spec notes a key carries the full authority of its account, with no scopes or read-only keys. Through Jentic the key is held by your own instance and injected at call time.

### Why does the NudgeHost v1 API refuse my key as unauthorized?

Check the host. The apex nudgehost.com answers with a 308 redirect to www.nudgehost.com, and clients drop the Authorization header on that cross-origin hop, so the call arrives without a credential. Point your client at https://www.nudgehost.com directly.

### What are the rate limits for the NudgeHost v1 API?

The spec states requests are counted per key over a one-minute window: 20 per minute on the free plan, 60 on Pro, and 150 on Studio. Going over returns rate_limited with a Retry-After header, and there are no headers reporting remaining quota, so pace calls yourself.

### How does uploading work with the NudgeHost v1 API?

It takes two calls and a PUT. POST `/api/v1/uploads` with filename, contentType, and fileSize returns a presigned upload.url, you PUT exactly fileSize bytes to it before expiresInSeconds runs out, and then POST `/api/v1/uploads/{id}/complete` returns the final url and kind. If complete reports upload_incomplete, the id is spent and you start a new upload.

### How do I upload a file and share the link through Jentic?

Search Jentic for 'upload a file and get a shareable link', load the NudgeHost start-upload operation, and send the filename, contentType, and fileSize. After the bytes are PUT to the returned upload.url, call the complete operation and hand the user the url it returns. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Is there a NudgeHost MCP server?

You do not need an MCP server to give your agent NudgeHost. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls the upload, list, and delete operations it needs on demand.

### Can I limit what my agent is allowed to do with the NudgeHost v1 API?

Yes, and it matters here because a NudgeHost key has no scopes of its own. Write a rule that allows POST `/api/v1/uploads`, POST `/api/v1/uploads/{id}/complete`, and GET `/api/v1/files`, and the agent can publish and list files but cannot call DELETE `/api/v1/files/{id}.` The calls it makes are logged for review.