# API Reference

GPM provides a comprehensive REST API for programmatic access to package management functionality. The API follows industry-standard conventions and provides full access to all GPM features.

## API Overview

### Base URLs

* **Global Registry**: `https://registry.gpm.sh`
* **Tenant Registries**: `https://<tenant>.gpm.sh`

### Authentication

GPM uses npm-compatible authentication via `PUT /-/user/org.couchdb.user:*`:

```bash
# Login via API
curl -X PUT https://registry.gpm.sh/-/user/org.couchdb.user:username \
  -H "Content-Type: application/json" \
  -d '{"name": "username", "password": "password", "email": "user@example.com"}'
```

### Content Types

* **Request**: `application/json`
* **Response**: `application/json`

## Authentication Endpoints

### Login

Authenticate with the registry and receive an authentication token.

**Endpoint**: `PUT /-/user/org.couchdb.user:<username>`

**Request Body**:

```json
{
  "name": "username",
  "password": "password",
  "email": "user@example.com"
}
```

**Response**:

```json
{
  "ok": true,
  "id": "org.couchdb.user:username",
  "rev": "1-abc123def456",
  "token": "npm_abc123def456ghi789"
}
```

### Logout

Invalidate authentication token.

**Endpoint**: `DELETE /-/user/token/<token>`

**Response**:

```json
{
  "ok": true
}
```

### Who Am I

Get current user information.

**Endpoint**: `GET /-/whoami`

**Headers**: `Authorization: Bearer <token>`

**Response**:

```json
{
  "username": "username",
  "email": "user@example.com",
  "registry": "https://registry.gpm.sh"
}
```

## Package Endpoints

### Get Package Information

Retrieve package metadata and version information.

**Endpoint**: `GET /<package>`

**Example**: `GET /com.unity.analytics`

**Response**:

```json
{
  "name": "com.unity.analytics",
  "description": "Analytics and insights for Unity games",
  "dist-tags": {
    "latest": "2.1.0"
  },
  "versions": {
    "2.1.0": {
      "name": "com.unity.analytics",
      "version": "2.1.0",
      "description": "Analytics and insights for Unity games",
      "author": "Unity Technologies <support@unity3d.com>",
      "license": "MIT",
      "unity": "2021.3",
      "dependencies": {
        "com.unity.services.core": "1.10.1"
      },
      "dist": {
        "tarball": "https://cdn.gpm.sh/tarballs/com.unity.analytics/2.1.0.tgz",
        "integrity": "sha512-rjzUCACnBKOYRtn2Ttv67MRXFDNLsL1FSTgzyp4m6IYGErjRyYFJBO0O9cfjFrB1j79WvCR072HSe4a31ug1tQ=="
      }
    }
  }
}
```

### Get Specific Version

Retrieve information for a specific package version.

**Endpoint**: `GET /<package>/<version>`

**Example**: `GET /com.unity.analytics/2.1.0`

**Response**:

```json
{
  "name": "com.unity.analytics",
  "version": "2.1.0",
  "description": "Analytics and insights for Unity games",
  "author": "Unity Technologies <support@unity3d.com>",
  "license": "MIT",
  "unity": "2021.3",
  "dependencies": {
    "com.unity.services.core": "1.10.1"
  },
  "dist": {
    "tarball": "https://cdn.gpm.sh/tarballs/com.unity.analytics/2.1.0.tgz",
    "integrity": "sha512-rjzUCACnBKOYRtn2Ttv67MRXFDNLsL1FSTgzyp4m6IYGErjRyYFJBO0O9cfjFrB1j79WvCR072HSe4a31ug1tQ=="
  }
}
```

### Download Package

Download package tarball.

**Endpoint**: `GET /<package>/-/<filename>`

**Example**: `GET /com.unity.analytics/-/com.unity.analytics-2.1.0.tgz`

**Response**: Binary tarball file

### Publish Package

Publish a new package version.

**Endpoint**: `PUT /<package>`

**Headers**: `Authorization: Bearer <token>`

**Request Body**: npm-compatible publish payload

**Response**:

```json
{
  "ok": true,
  "id": "com.unity.analytics",
  "rev": "1-abc123def456"
}
```

## Search Endpoints

### Search Packages

Search for packages by name, description, or keywords.

**Endpoint**: `GET /-/v1/search`

**Query Parameters**:

* `text`: Search query
* `size`: Number of results (default: 20)
* `from`: Offset for pagination (default: 0)

**Example**: `GET /-/v1/search?text=unity&size=10&from=0`

**Response**:

```json
{
  "objects": [
    {
      "package": {
        "name": "com.unity.analytics",
        "version": "2.1.0",
        "description": "Analytics and insights for Unity games",
        "keywords": ["unity", "analytics", "insights"],
        "author": "Unity Technologies",
        "date": "2024-01-15T10:30:00.000Z"
      },
      "score": {
        "final": 0.95,
        "detail": {
          "quality": 0.9,
          "popularity": 0.8,
          "maintenance": 1.0
        }
      }
    }
  ],
  "total": 150,
  "time": "2024-01-15T10:30:00.000Z"
}
```

## Distribution Tag Endpoints

### List Distribution Tags

Get all distribution tags for a package.

**Endpoint**: `GET /-/package/<package>/dist-tags`

**Example**: `GET /-/package/com.unity.analytics/dist-tags`

**Response**:

```json
{
  "latest": "2.1.0",
  "beta": "2.2.0-beta.1",
  "alpha": "2.3.0-alpha.1"
}
```

### Add Distribution Tag

Add a new distribution tag.

**Endpoint**: `PUT /-/package/<package>/dist-tags/<tag>`

**Headers**: `Authorization: Bearer <token>`

**Request Body**:

```json
"2.1.0"
```

**Response**:

```json
{
  "ok": true
}
```

### Remove Distribution Tag

Remove a distribution tag.

**Endpoint**: `DELETE /-/package/<package>/dist-tags/<tag>`

**Headers**: `Authorization: Bearer <token>`

**Response**:

```json
{
  "ok": true
}
```

## Error Handling

### Error Response Format

```json
{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": "Additional error details"
}
```

### Common Error Codes

* `400`: Bad Request - Invalid request format
* `401`: Unauthorized - Authentication required
* `403`: Forbidden - Insufficient permissions
* `404`: Not Found - Package or version not found
* `409`: Conflict - Package already exists
* `422`: Unprocessable Entity - Validation error
* `500`: Internal Server Error - Server error

### Error Examples

#### Package Not Found

```json
{
  "error": "Package not found",
  "code": "NOT_FOUND",
  "details": "Package 'com.nonexistent.package' not found"
}
```

#### Authentication Required

```json
{
  "error": "Authentication required",
  "code": "UNAUTHORIZED",
  "details": "Valid authentication token required"
}
```

#### Validation Error

```json
{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": "Package name must use reverse-DNS format"
}
```

## Rate Limiting

### Rate Limits

* **Anonymous**: 100 requests per hour
* **Authenticated**: 1000 requests per hour
* **Publishing**: 10 requests per hour

### Rate Limit Headers

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
```

### Rate Limit Exceeded

```json
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": "Rate limit of 1000 requests per hour exceeded"
}
```

## API Examples

### Complete Workflow

```bash
# 1. Login
curl -X PUT https://registry.gpm.sh/-/user/org.couchdb.user:username \
  -H "Content-Type: application/json" \
  -d '{"name": "username", "password": "password", "email": "user@example.com"}'

# 2. Search packages
curl "https://registry.gpm.sh/-/v1/search?text=unity&size=10"

# 3. Get package info
curl "https://registry.gpm.sh/com.unity.analytics"

# 4. Download package
curl "https://registry.gpm.sh/com.unity.analytics/-/com.unity.analytics-2.1.0.tgz" \
  -o com.unity.analytics-2.1.0.tgz

# 5. Publish package
curl -X PUT https://registry.gpm.sh/com.company.mypackage \
  -H "Authorization: Bearer npm_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d @package-payload.json
```

### JavaScript/Node.js Example

```javascript
const axios = require('axios');

const registry = 'https://registry.gpm.sh';

// Search packages
async function searchPackages(query) {
  const response = await axios.get(`${registry}/-/v1/search`, {
    params: { text: query, size: 10 }
  });
  return response.data;
}

// Get package info
async function getPackageInfo(packageName) {
  const response = await axios.get(`${registry}/${packageName}`);
  return response.data;
}

// Download package
async function downloadPackage(packageName, version) {
  const response = await axios.get(
    `${registry}/${packageName}/-/${packageName}-${version}.tgz`,
    { responseType: 'stream' }
  );
  return response.data;
}
```

### Python Example

```python
import requests
import json

registry = 'https://registry.gpm.sh'

def search_packages(query):
    response = requests.get(f'{registry}/-/v1/search', 
                          params={'text': query, 'size': 10})
    return response.json()

def get_package_info(package_name):
    response = requests.get(f'{registry}/{package_name}')
    return response.json()

def download_package(package_name, version):
    response = requests.get(
        f'{registry}/{package_name}/-/{package_name}-{version}.tgz',
        stream=True
    )
    return response.content
```

## SDKs and Libraries

### Official SDKs

* **JavaScript/Node.js**: Built into GPM CLI
* **Python**: `gpm-python` (planned)
* **Go**: `gpm-go` (planned)
* **C#**: `GPM.NET` (planned)

### Community Libraries

* **Rust**: `gpm-rs` (community)
* **PHP**: `gpm-php` (community)
* **Ruby**: `gpm-ruby` (community)

## See Also

* [CLI Reference](/cli-reference/cli.md) - Command-line interface
* [Package Management](/cli-reference/cli/package-management.md) - Package operations
* [Publishing](/cli-reference/cli/publishing.md) - Package publishing
* [Authentication](/cli-reference/cli/authentication.md) - User authentication


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gpm.sh/api-reference/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.