API Reference

CloudRepo provides a comprehensive REST API for programmatic access to all features.

Overview

The CloudRepo API enables you to:

Manage repositories programmatically
Automate user and permission management
Upload and download artifacts
Search and query metadata
Configure webhooks and integrations
Access analytics and metrics

Base URL

All API requests use the following base URL:

https://[org-id].cloudrepo.io/api

Replace [org-id] with your organization identifier.

Authentication

The API supports two authentication methods:

Basic Authentication

Use your CloudRepo username and password:

curl -u username:password \
  https://[org-id].cloudrepo.io/api/user

API Key Authentication

Use an API key for automated access:

curl -u api-key:your-api-key-here \
  https://[org-id].cloudrepo.io/api/user

Request Headers

Content-Type: application/json
Accept: application/json

User Management

Get Current User

GET /api/user

Response:

{
  "username": "john.doe",
  "email": "john@example.com",
  "role": "admin",
  "created": "2024-01-15T10:00:00Z"
}

List All Users

GET /api/users

Response:

{
  "users": [
    {
      "username": "john.doe",
      "email": "john@example.com",
      "role": "admin"
    },
    {
      "username": "jane.smith",
      "email": "jane@example.com",
      "role": "developer"
    }
  ]
}

Create User

POST /api/users

Request Body:

{
  "email": "new.user@example.com",
  "role": "developer",
  "repositories": ["maven-releases", "maven-snapshots"]
}

Update User Permissions

PUT /api/users/{username}/permissions

Request Body:

{
  "repositories": {
    "maven-releases": ["read", "write"],
    "python-releases": ["read"]
  }
}

Delete User

DELETE /api/users/{username}

Repository Management

List Repositories

GET /api/repositories

Response:

{
  "repositories": [
    {
      "name": "maven-releases",
      "type": "maven2",
      "format": "release",
      "visibility": "private",
      "created": "2024-01-01T00:00:00Z",
      "size": "1.2GB"
    }
  ]
}

Get Repository Details

GET /api/repositories/{name}

Create Repository

POST /api/repositories

Request Body:

{
  "name": "new-repository",
  "type": "maven2",
  "format": "release",
  "visibility": "private",
  "description": "Production releases"
}

Update Repository

PUT /api/repositories/{name}

Request Body:

{
  "description": "Updated description",
  "visibility": "public"
}

Delete Repository

DELETE /api/repositories/{name}

Warning: This permanently deletes all artifacts in the repository.

Artifact Operations

Upload Artifact

PUT /repository/{repo-name}/{path}

Example - Maven:

curl -u username:password \
  --upload-file myapp-1.0.jar \
  https://[org-id].cloudrepo.io/repository/maven-releases/com/example/myapp/1.0/myapp-1.0.jar

Example - Python:

curl -u username:password \
  --upload-file package-1.0.tar.gz \
  https://[org-id].cloudrepo.io/repository/pypi/packages/package-1.0.tar.gz

Download Artifact

GET /repository/{repo-name}/{path}

Delete Artifact

DELETE /repository/{repo-name}/{path}

List Artifacts

GET /api/repositories/{name}/artifacts

Query Parameters:

path - Filter by path prefix
limit - Maximum results (default: 100)
offset - Pagination offset

Response:

{
  "artifacts": [
    {
      "path": "com/example/myapp/1.0/myapp-1.0.jar",
      "size": 1024000,
      "checksum": "sha256:abc123...",
      "uploaded": "2024-01-15T10:00:00Z"
    }
  ],
  "total": 150,
  "limit": 100,
  "offset": 0
}

Search API

Search Artifacts

GET /api/search

Query Parameters:

q - Search query
repository - Filter by repository
type - Filter by artifact type

Example:

curl -u username:password \
  "https://[org-id].cloudrepo.io/api/search?q=spring&repository=maven-releases"

Advanced Search

POST /api/search/advanced

Request Body:

{
  "query": {
    "groupId": "com.example",
    "artifactId": "myapp",
    "version": "1.*"
  },
  "repositories": ["maven-releases"],
  "sort": "version",
  "order": "desc"
}

API Keys Management

List API Keys

GET /api/keys

Create API Key

POST /api/keys

Request Body:

{
  "name": "CI/CD Key",
  "permissions": {
    "repositories": {
      "maven-releases": ["read", "write"]
    }
  },
  "expiresIn": "90d"
}

Response:

{
  "key": "cr_1234567890abcdef",
  "name": "CI/CD Key",
  "created": "2024-01-15T10:00:00Z",
  "expires": "2024-04-15T10:00:00Z"
}

Revoke API Key

DELETE /api/keys/{key-id}

Webhooks

List Webhooks

GET /api/webhooks

Create Webhook

POST /api/webhooks

Request Body:

{
  "name": "Deploy Hook",
  "url": "https://example.com/webhook",
  "events": ["artifact.uploaded", "artifact.deleted"],
  "repositories": ["maven-releases"],
  "secret": "webhook-secret"
}

Test Webhook

POST /api/webhooks/{id}/test

Analytics API

Repository Statistics

GET /api/repositories/{name}/stats

Response:

{
  "totalArtifacts": 1500,
  "totalSize": "5.2GB",
  "downloads": {
    "today": 150,
    "week": 1200,
    "month": 5000
  },
  "uploads": {
    "today": 10,
    "week": 75,
    "month": 300
  }
}

Download Analytics

GET /api/analytics/downloads

Query Parameters:

from - Start date (ISO 8601)
to - End date (ISO 8601)
repository - Filter by repository
granularity - hour, day, week, month

Error Handling

Error Responses

Errors return appropriate HTTP status codes:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid credentials",
    "details": "Authentication failed for user: john.doe"
  }
}

Status Codes

200 OK - Success
201 Created - Resource created
400 Bad Request - Invalid request
401 Unauthorized - Authentication required
403 Forbidden - Access denied
404 Not Found - Resource not found
409 Conflict - Resource already exists
500 Internal Server Error - Server error

Rate Limiting

API requests are rate-limited:

Default: 1000 requests per hour
Enterprise: 10000 requests per hour

Rate limit information in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1642248000

Code Examples

Python Example

import requests
from requests.auth import HTTPBasicAuth

class CloudRepoClient:
    def __init__(self, org_id, username, password):
        self.base_url = f"https://{org_id}.cloudrepo.io/api"
        self.auth = HTTPBasicAuth(username, password)

    def list_repositories(self):
        response = requests.get(
            f"{self.base_url}/repositories",
            auth=self.auth
        )
        return response.json()

    def upload_artifact(self, repo, path, file_path):
        with open(file_path, 'rb') as f:
            response = requests.put(
                f"{self.base_url.replace('/api', '')}/repository/{repo}/{path}",
                data=f,
                auth=self.auth
            )
        return response.status_code == 201

# Usage
client = CloudRepoClient("my-org", "username", "password")
repos = client.list_repositories()
print(repos)

JavaScript Example

const axios = require('axios');

class CloudRepoClient {
  constructor(orgId, username, password) {
    this.baseURL = `https://${orgId}.cloudrepo.io/api`;
    this.auth = {
      username: username,
      password: password
    };
  }

  async listRepositories() {
    const response = await axios.get(
      `${this.baseURL}/repositories`,
      { auth: this.auth }
    );
    return response.data;
  }

  async createRepository(name, type) {
    const response = await axios.post(
      `${this.baseURL}/repositories`,
      {
        name: name,
        type: type,
        format: 'release',
        visibility: 'private'
      },
      { auth: this.auth }
    );
    return response.data;
  }
}

// Usage
const client = new CloudRepoClient('my-org', 'username', 'password');
client.listRepositories().then(console.log);

Shell Script Example

#!/bin/bash

ORG_ID="my-org"
USERNAME="username"
PASSWORD="password"
BASE_URL="https://${ORG_ID}.cloudrepo.io/api"

# List repositories
curl -u "${USERNAME}:${PASSWORD}" \
  "${BASE_URL}/repositories" | jq '.'

# Upload artifact
curl -u "${USERNAME}:${PASSWORD}" \
  --upload-file myapp.jar \
  "https://${ORG_ID}.cloudrepo.io/repository/maven-releases/com/example/myapp/1.0/myapp-1.0.jar"

# Create webhook
curl -u "${USERNAME}:${PASSWORD}" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deploy Hook",
    "url": "https://example.com/webhook",
    "events": ["artifact.uploaded"]
  }' \
  "${BASE_URL}/webhooks"

Next Steps

Test API calls using the examples above
Implement automation scripts
Set up webhooks for event notifications
Review Continuous Integration and Deployment for CI/CD integration