REST API v1 Reference

The NG REST API allows developers to list and submit apps, retrieve user information, and manage installations programmatically. The API is available at https://ng.net/api/v1 and supports both browser session cookies and Bearer API keys for authentication.

API v1 Stable Updated April 2026

Base URL

All API requests are made to the following base URL:

https://ng.net/api/v1

All responses are JSON. Requests that include a body should set Content-Type: application/json.

Authentication

The API supports two authentication methods. Endpoints marked with Auth Required require one of these methods.

Bearer Token (API Key)

Use a Bearer token for server-side applications, CLI tools, or scripts. Generate API keys in the NG App Store developer dashboard.

Authorization: Bearer ng_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Session Cookie

Browser requests from authenticated NG Desktop users are automatically authenticated via session cookie. This is the recommended method for apps running inside NG Desktop via the NG Connect SDK.

Note: API keys are scoped to the app they belong to. A key generated for App A authenticates as the developer/owner of App A and cannot be used to manage other apps.

Rate Limits

The API uses Cloudflare Workers rate limiting. Current limits are:

Endpoint Type	Limit	Window
Public endpoints (GET /apps)	200 requests	per minute
Authenticated endpoints	60 requests	per minute
App submission (POST /apps)	5 requests	per hour

Endpoints

GET /api/v1/apps

List Apps

Returns a paginated list of approved apps in the NG App Store. This endpoint is public and does not require authentication. Use the q parameter to search, or category and app_type to filter.

Query Parameters

Parameter	Type	Default	Description
`category`	string	—	Filter by category (e.g. `tools`, `ai`, `productivity`)
`app_type`	string	—	Filter by type: `web`, `pwa`, or `dapp`
`q`	string	—	Full-text search across name, description, and tags
`limit`	integer	50	Max results per page (max 100)
`offset`	integer	0	Pagination offset

Response

{
  "apps": [
    {
      "id": "abc123",
      "slug": "my-app",
      "name": "My App",
      "description": "A great app",
      "url": "https://myapp.com",
      "category": "tools",
      "app_type": "web",
      "open_mode": "iframe",
      "status": "approved",
      "downloads": 142,
      "author_name": "Jane Dev"
    }
  ],
  "meta": { "limit": 50, "offset": 0, "count": 1 }
}

POST /api/v1/apps Auth Required

Submit App

Submit a new app to the NG App Store. Requires authentication via Bearer token or session cookie. NG uses an open listing model — apps are automatically approved and go live immediately (status: "approved"). No waiting, no manual review.

Request Body

Field	Type	Required	Description
`slug`	string	Yes	URL-safe unique identifier (e.g. `my-app`)
`name`	string	Yes	Display name of the app
`url`	string	Yes	App URL (must be HTTPS)
`description`	string	No	App description shown in the store
`category`	string	No	App category (default: `tools`)
`app_type`	string	No	`web` \| `pwa` \| `dapp` (default: `web`)
`open_mode`	string	No	`iframe` \| `external` (default: `iframe`)
`chain`	string	No	Blockchain identifier for dApps (e.g. `ethereum`)

Response (201 Created)

{
  "id": "abc123",
  "slug": "my-app",
  "status": "approved"
}

GET /api/v1/apps/{slug}

Get App Detail

Returns full details for a single approved app by its slug. Only returns apps with status: "approved".

PATCH /api/v1/apps/{slug} Auth Required

Update App

Update app metadata. Requires authentication as the app's author. Updatable fields: name, description, icon_gradient_from, icon_gradient_to, icon_svg, tech_tags, category, chain, ng_sdk_version.

POST /api/v1/apps/{slug}/report Auth Required

Report App

Report an app for violating platform policies. Each user can report an app once. When 5 unique users report the same app, it is automatically removed from the App Store (status: "blocked").

Request Body

Field	Type	Required	Description
`reason`	string	No	One of: `spam`, `malware`, `phishing`, `illegal`, `inappropriate`, `other` (default: `other`)
`detail`	string	No	Additional description of the issue (max 500 chars)

Response (200 OK)

{
  "success": true,
  "report_count": 3,
  "blocked": false,
  "message": "Report recorded. 2 more report(s) needed to trigger auto-block."
}

// When threshold is reached (5 reports):
{
  "success": true,
  "report_count": 5,
  "blocked": true,
  "message": "App has been automatically blocked due to multiple reports."
}

Error Responses

Status	Error	Reason
401	`Authentication required`	Not logged in
404	`App not found`	Slug does not exist
409	`You have already reported this app`	Duplicate report from same user
409	`App is already blocked`	App has already been removed

GET /api/v1/me Auth Required

Get Current User

Returns profile information for the currently authenticated user.

Response

{
  "user": {
    "id": "user_xyz",
    "display_name": "Jane Dev",
    "email": "jane@example.com",
    "avatar_url": "https://lh3.googleusercontent.com/..."
  }
}

GET /api/v1/me/apps Auth Required

Get My Apps

Returns all apps submitted by the authenticated user, including apps with any status (approved, blocked).

GET /api/v1/me/installed Auth Required

Get Installed Apps

Returns the list of apps that the authenticated user has installed in their NG Desktop. Only approved apps are included.

Request Examples

The following examples use curl. Replace ng_xxxxxxxx with your actual API key.

List approved apps

# List all approved apps
curl https://ng.net/api/v1/apps

# Filter by type
curl "https://ng.net/api/v1/apps?app_type=pwa&limit=20"

# Search
curl "https://ng.net/api/v1/apps?q=productivity"

Submit a new app

curl -X POST https://ng.net/api/v1/apps \
  -H "Authorization: Bearer ng_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-app",
    "name": "My App",
    "url": "https://myapp.com",
    "description": "A productivity tool for NG Desktop users",
    "category": "productivity",
    "app_type": "pwa"
  }'

Get current user

curl https://ng.net/api/v1/me \
  -H "Authorization: Bearer ng_xxxxxxxxxxxxxxxx"

Error Codes

The API uses standard HTTP status codes. Error responses always include a JSON body with an error field describing the problem.

Status	Code	Meaning
400	Bad Request	Missing or invalid required fields
401	Unauthorized	No valid authentication provided
403	Forbidden	Authenticated but not allowed (e.g. not the app author)
404	Not Found	App with given slug not found or not approved
409	Conflict	Slug is already taken by another app
503	Service Unavailable	Database temporarily unavailable

// Error response format
{
  "error": "Slug already taken"
}

Frequently Asked Questions

How do I get an API key?

Log in to ng.net, open the App Store, go to the Developer tab, select your app, and click "Create Key" in the API Keys section. Each key is scoped to one app.

Can I use the API without submitting an app?

The public GET /api/v1/apps endpoint works without any authentication. For authenticated endpoints, you need at least one app submitted to generate an API key.

What is the difference between the REST API and NG Connect SDK?

The REST API is for server-side or CLI access to NG platform data (app listings, user info). The NG Connect SDK runs inside the browser in your app and communicates with NG Desktop via postMessage — it provides login, notifications, storage, and social features without any backend.

Is the API rate-limited?

Yes. Public endpoints allow 200 requests per minute. Authenticated endpoints allow 60 requests per minute. App submission is limited to 5 per hour.