Apps API

The Apps API allows you to register, manage, and retrieve information about your applications on the GetJar platform. Apps are the foundation of your integration and enable features like achievements, leaderboards, and in-app purchases.

Authentication

Most endpoints require authentication using either:

API Key: Include x-api-key header
Cognito JWT: Include Authorization: Bearer <token> header
Developer Auth: Special authentication for developer operations

The getAppById endpoint is public and doesn't require authentication.

Base URL

https://sdk.getjar.com/apps

Create App

Endpoint

POST /apps

Request Body

{
  developerId: string;          // Required: Developer ID
  name: string;                 // Required: App name
  description?: string;         // App description
  platforms: string[];          // Required: Supported platforms
  categories?: string[];        // App categories
  pictureUrl?: string;          // App icon URL
  getjarUrl?: string;           // Public GetJar URL
  isActive?: boolean;           // Default: true
  isPublic?: boolean;           // Default: false
  metadata?: object;            // Custom metadata
}

Platforms

Supported platform values:

WINDOWS
MAC
LINUX
IOS
ANDROID
WEB

Response

{
  appId: string;
  developerId: string;
  name: string;
  description: string;
  platforms: string[];
  categories: string[];
  pictureUrl: string;
  getjarUrl: string;
  isActive: boolean;
  isPublic: boolean;
  createdAt: string;
  updatedAt: string;
}

Example

import { AppsApi } from "@getjar-iap/sdk";

const appsApi = new AppsApi(configuration);

const app = await appsApi.createApp({
  createAppDto: {
    developerId: "dev_123",
    name: "Awesome Game",
    description: "An epic adventure game with stunning graphics",
    platforms: ["WINDOWS", "MAC", "WEB"],
    categories: ["action", "adventure", "multiplayer"],
    isActive: true,
    isPublic: false,
    metadata: {
      genre: "RPG",
      rating: "E10+",
      releaseYear: 2025,
    },
  },
});

console.log("App ID:", app.data.appId);
console.log("App URL:", app.data.getjarUrl);

Response Codes

Code	Description
201	App created successfully
400	Invalid app data
401	Unauthorized
403	Insufficient permissions

Update App

Update an existing app's details.

Endpoint

PUT /apps/:appId

Parameters

Parameter	Type	Description
appId	string	The unique application identifier

Request Body

{
  name?: string;
  description?: string;
  platforms?: string[];
  categories?: string[];
  pictureUrl?: string;
  isActive?: boolean;
  isPublic?: boolean;
  metadata?: object;
}

Example

const updated = await appsApi.updateApp({
  appId: "app_123",
  updateAppDto: {
    name: "Awesome Game - Remastered",
    description: "An epic adventure game with new features",
    platforms: ["WINDOWS", "MAC", "LINUX", "WEB"],
    isPublic: true,
    metadata: {
      genre: "RPG",
      rating: "E10+",
      releaseYear: 2025,
      version: "2.0",
    },
  },
});

console.log("Updated:", updated.data);

Response Codes

Code	Description
200	App updated successfully
400	Invalid update data
401	Unauthorized
403	Not the app owner
404	App not found

Get App by ID

Retrieve detailed information about a specific app. This endpoint is public.

Endpoint

GET /apps/:appId

Parameters

Parameter	Type	Description
appId	string	The unique application identifier

Response

{
  appId: string;
  developerId: string;
  gameId?: string;              // Strapi game ID
  gameDocumentId?: string;      // Strapi document ID
  name: string;
  description: string;
  platforms: string[];
  categories: string[];
  pictureUrl?: string;
  pictureKey?: string;          // S3 storage key
  pictureUploadedAt?: string;
  pictureLastGeneratedAt?: string;
  getjarUrl: string;
  isActive: boolean;
  isPublic: boolean;
  metadata?: object;
  createdAt: string;
  updatedAt: string;
}

Example

const app = await appsApi.getAppById({
  appId: "app_123",
});

console.log("App Name:", app.data.name);
console.log("Description:", app.data.description);
console.log("Platforms:", app.data.platforms);
console.log("Categories:", app.data.categories);
console.log("Public URL:", app.data.getjarUrl);

Response Codes

Code	Description
200	Success
404	App not found

Get Developer Apps

Retrieve all apps owned by a specific developer with pagination.

Endpoint

GET /apps/developer/:developerId

Parameters

Parameter	Type	Required	Description
developerId	string	Yes	The developer identifier
page	number	No	Page number (default: 1)
pageSize	number	No	Items per page (default: 25)

Response

{
  data: Array<{
    appId: string;
    developerId: string;
    name: string;
    description: string;
    platforms: string[];
    categories: string[];
    pictureUrl?: string;
    isActive: boolean;
    isPublic: boolean;
    createdAt: string;
  }>;
  meta: {
    pagination: {
      page: number;
      pageSize: number;
      pageCount: number;
      total: number;
    }
  }
}

Example

const developerApps = await appsApi.getDeveloperApps({
  developerId: "dev_123",
  page: 1,
  pageSize: 25,
});

console.log(`Total Apps: ${developerApps.data.meta.pagination.total}`);
console.log(
  `Page ${developerApps.data.meta.pagination.page} of ${developerApps.data.meta.pagination.pageCount}`
);

developerApps.data.data.forEach((app) => {
  console.log(`- ${app.name} (${app.platforms.join(", ")})`);
});

Response Codes

Code	Description
200	Success
401	Unauthorized
404	Developer not found

Check if App Exists

Verify whether an app with a given ID exists.

Endpoint

GET /apps/:appId/exists

Parameters

Parameter	Type	Description
appId	string	The application identifier to check

Response

{
  exists: boolean;
}

Example

const result = await appsApi.checkAppExists({
  appId: "app_123",
});

if (result.data.exists) {
  console.log("App exists!");
} else {
  console.log("App not found");
}

Response Codes

Code	Description
200	Success
401	Unauthorized

App Platforms

Apps can support multiple platforms simultaneously. Each platform has specific considerations:

Desktop Platforms

Platform	Description	Use Cases
WINDOWS	Windows PC	Desktop games, productivity apps
MAC	macOS	Desktop games, productivity apps
LINUX	Linux distributions	Cross-platform games, tools

Mobile Platforms

Platform	Description	Use Cases
IOS	iPhone and iPad	Mobile games, apps
ANDROID	Android devices	Mobile games, apps

Web Platform

Platform	Description	Use Cases
WEB	Browser-based	Web games, HTML5 apps

Example: Multi-Platform App

const crossPlatformApp = await appsApi.createApp({
  createAppDto: {
    developerId: "dev_123",
    name: "Cross-Platform Game",
    description: "Play anywhere, on any device",
    platforms: ["WINDOWS", "MAC", "LINUX", "IOS", "ANDROID", "WEB"],
    categories: ["action", "multiplayer", "cross-platform"],
    isPublic: true,
  },
});

App Categories

Organize your apps with categories for better discoverability:

Example: Categorizing Your App

const app = await appsApi.createApp({
  createAppDto: {
    developerId: "dev_123",
    name: "Space Explorer",
    description: "Explore the universe in this epic space adventure",
    platforms: ["WINDOWS", "MAC", "WEB"],
    categories: ["adventure", "strategy", "simulation", "indie", "multiplayer"],
    isPublic: true,
  },
});

Complete Example

Here's a complete workflow for setting up a new app:

import { Configuration, AppsApi } from "@getjar-iap/sdk";

const configuration = new Configuration({
  basePath: "https://sdk.getjar.com",
  apiKey: "your-api-key",
});

const appsApi = new AppsApi(configuration);

async function setupNewApp() {
  const developerId = "dev_123";

  try {
    // 1. Create the app
    console.log("Creating app...");
    const app = await appsApi.createApp({
      createAppDto: {
        developerId,
        name: "My Awesome Game",
        description: "An epic multiplayer adventure game",
        platforms: ["WINDOWS", "MAC", "WEB"],
        categories: ["action", "adventure", "multiplayer"],
        isActive: true,
        isPublic: false, // Keep private during development
        metadata: {
          genre: "Action RPG",
          rating: "T",
          releaseYear: 2025,
          engine: "Unity",
          version: "1.0.0",
        },
      },
    });

    const appId = app.data.appId;
    console.log("✓ App created:", appId);
    console.log("  Name:", app.data.name);
    console.log("  URL:", app.data.getjarUrl);

    // 2. Verify app exists
    console.log("\nVerifying app...");
    const exists = await appsApi.checkAppExists({ appId });
    console.log("✓ App verified:", exists.data.exists);

    // 3. Get app details
    console.log("\nFetching app details...");
    const appDetails = await appsApi.getAppById({ appId });
    console.log("✓ App details retrieved");
    console.log("  Platforms:", appDetails.data.platforms);
    console.log("  Categories:", appDetails.data.categories);
    console.log("  Active:", appDetails.data.isActive);
    console.log("  Public:", appDetails.data.isPublic);

    // 4. Update app (add more platforms)
    console.log("\nUpdating app...");
    const updated = await appsApi.updateApp({
      appId,
      updateAppDto: {
        platforms: ["WINDOWS", "MAC", "LINUX", "WEB"],
        description: "An epic multiplayer adventure game - Now on Linux!",
        metadata: {
          genre: "Action RPG",
          rating: "T",
          releaseYear: 2025,
          engine: "Unity",
          version: "1.1.0",
          changelog: "Added Linux support",
        },
      },
    });
    console.log("✓ App updated");
    console.log("  New platforms:", updated.data.platforms);

    // 5. List all apps by developer
    console.log("\nListing all developer apps...");
    const developerApps = await appsApi.getDeveloperApps({
      developerId,
      page: 1,
      pageSize: 10,
    });
    console.log(`✓ Found ${developerApps.data.meta.pagination.total} apps`);
    developerApps.data.data.forEach((app, index) => {
      console.log(`  ${index + 1}. ${app.name}`);
    });

    return {
      appId,
      appUrl: app.data.getjarUrl,
      platforms: updated.data.platforms,
    };
  } catch (error) {
    console.error("Error setting up app:", error);
    throw error;
  }
}

// Run the setup
setupNewApp()
  .then((result) => {
    console.log("\n✓ Setup complete!");
    console.log("App ID:", result.appId);
    console.log("App URL:", result.appUrl);
  })
  .catch((error) => {
    console.error("Setup failed:", error);
  });

App Lifecycle

Development Phase

// Create app in private mode
const app = await appsApi.createApp({
  createAppDto: {
    developerId: "dev_123",
    name: "My Game",
    platforms: ["WINDOWS", "WEB"],
    isActive: true,
    isPublic: false, // Private during development
  },
});

Testing Phase

// Keep private but active for testing
await appsApi.updateApp({
  appId: "app_123",
  updateAppDto: {
    isActive: true,
    isPublic: false,
  },
});

Launch Phase

// Make public when ready to launch
await appsApi.updateApp({
  appId: "app_123",
  updateAppDto: {
    isActive: true,
    isPublic: true, // Now publicly visible
  },
});

Maintenance Mode

// Temporarily disable for maintenance
await appsApi.updateApp({
  appId: "app_123",
  updateAppDto: {
    isActive: false,
    metadata: {
      maintenanceMode: true,
      maintenanceMessage: "Scheduled maintenance in progress",
    },
  },
});

Best Practices

App Registration

Choose Clear Names: Use descriptive, searchable names
Write Good Descriptions: Explain what makes your app unique
Select Accurate Categories: Help users discover your app
Set Appropriate Visibility: Use isPublic: false during development
Use Metadata: Store version info, changelogs, and custom data

Multi-Platform Support

Test Each Platform: Verify functionality on all supported platforms
Update Progressively: Roll out new platform support incrementally
Document Differences: Use metadata to note platform-specific features
Maintain Consistency: Keep core features consistent across platforms

App Management

Regular Updates: Keep app information current
Monitor Status: Check isActive and isPublic flags regularly
Version Tracking: Use metadata to track version history
URL Management: Ensure getjarUrl points to current landing page

Example: Versioning Strategy

// Initial release
await appsApi.createApp({
  createAppDto: {
    developerId: "dev_123",
    name: "My Game",
    platforms: ["WINDOWS", "WEB"],
    metadata: {
      version: "1.0.0",
      releaseDate: "2025-01-01",
      changelog: "Initial release",
    },
  },
});

// Major update
await appsApi.updateApp({
  appId: "app_123",
  updateAppDto: {
    metadata: {
      version: "2.0.0",
      releaseDate: "2025-06-01",
      changelog:
        "Major update: New features, bug fixes, performance improvements",
      previousVersions: ["1.0.0", "1.5.0"],
    },
  },
});

Metadata Best Practices

The metadata field allows you to store custom information about your app:

Recommended Metadata Fields

{
  metadata: {
    // Version Information
    version: '1.2.3',
    buildNumber: '12345',
    releaseDate: '2025-01-15',
    changelog: 'Bug fixes and improvements',

    // Technical Details
    engine: 'Unity',
    engineVersion: '2023.1',
    minSystemRequirements: {
      os: 'Windows 10',
      ram: '8GB',
      graphics: 'GTX 1060'
    },

    // Content Ratings
    rating: 'E10+',
    contentWarnings: ['Mild Violence'],

    // Marketing
    tagline: 'The Ultimate Adventure',
    featuredVideo: 'https://youtube.com/watch?v=...',
    screenshots: ['url1', 'url2', 'url3'],

    // Analytics
    downloads: 150000,
    activeUsers: 45000,
    averageRating: 4.5,

    // Support
    supportEmail: 'support@example.com',
    forumUrl: 'https://forum.example.com',
    discordUrl: 'https://discord.gg/...'
  }
}

Error Handling

try {
  const app = await appsApi.createApp({
    createAppDto: {
      /* ... */
    },
  });
} catch (error) {
  if (error.response) {
    const status = error.response.status;
    const message = error.response.data.message;

    switch (status) {
      case 400:
        console.error("Invalid app data:", message);
        break;
      case 401:
        console.error("Authentication required");
        break;
      case 403:
        console.error("Insufficient permissions");
        break;
      case 404:
        console.error("App or developer not found");
        break;
      default:
        console.error("Error:", message);
    }
  }
}

Pagination Example

When retrieving developer apps with many results:

async function getAllDeveloperApps(developerId: string) {
  const allApps = [];
  let currentPage = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await appsApi.getDeveloperApps({
      developerId,
      page: currentPage,
      pageSize: 25,
    });

    allApps.push(...response.data.data);

    const pagination = response.data.meta.pagination;
    hasMore = currentPage < pagination.pageCount;
    currentPage++;
  }

  return allApps;
}

// Usage
const allApps = await getAllDeveloperApps("dev_123");
console.log(`Total apps: ${allApps.length}`);

Integration with Other APIs

Once you've created an app, you can use its appId with other GetJar APIs:

Achievements

import { AchievementsApi } from "@getjar-iap/sdk";

const achievementsApi = new AchievementsApi(configuration);

await achievementsApi.createAchievement({
  createAchievementDto: {
    appId: "app_123", // Use your app ID here
    name: "First Victory",
    // ...
  },
});

Leaderboards

import { LeaderboardsApi } from "@getjar-iap/sdk";

const leaderboardsApi = new LeaderboardsApi(configuration);

await leaderboardsApi.createLeaderboard({
  appId: "app_123", // Use your app ID here
  createLeaderboardDto: {
    name: "Global Rankings",
    // ...
  },
});

Products

import { ProductsApi } from "@getjar-iap/sdk";

const productsApi = new ProductsApi(configuration);

await productsApi.createProduct({
  createProductDto: {
    appId: "app_123", // Use your app ID here
    name: "Gold Pack",
    // ...
  },
});

Support

For additional help or questions:

Documentation: https://docs.getjar.com
API Reference: https://sdk.getjar.com/api/docs
Support: support@getjar.com

Authentication​

Base URL​

Create App​

Endpoint​

Request Body​

Platforms​

Response​

Example​

Response Codes​

Update App​

Endpoint​

Parameters​

Request Body​

Example​

Response Codes​

Get App by ID​

Endpoint​

Parameters​

Response​

Example​

Response Codes​

Get Developer Apps​

Endpoint​

Parameters​

Response​

Example​

Response Codes​

Check if App Exists​

Endpoint​

Parameters​

Response​

Example​

Response Codes​

App Platforms​

Desktop Platforms​

Mobile Platforms​

Web Platform​

Example: Multi-Platform App​

App Categories​

Common Categories​

Example: Categorizing Your App​

Complete Example​

App Lifecycle​

Development Phase​

Testing Phase​

Launch Phase​

Maintenance Mode​

Best Practices​

App Registration​

Multi-Platform Support​

App Management​

Example: Versioning Strategy​

Metadata Best Practices​

Recommended Metadata Fields​

Error Handling​

Pagination Example​

Integration with Other APIs​

Achievements​

Leaderboards​

Products​

Support​

Authentication

Base URL

Create App

Endpoint

Request Body

Platforms

Response

Example

Response Codes

Update App

Endpoint

Parameters

Request Body

Example

Response Codes

Get App by ID

Endpoint

Parameters

Response

Example

Response Codes

Get Developer Apps

Endpoint

Parameters

Response

Example

Response Codes

Check if App Exists

Endpoint

Parameters

Response

Example

Response Codes

App Platforms

Desktop Platforms

Mobile Platforms

Web Platform

Example: Multi-Platform App

App Categories

Common Categories

Example: Categorizing Your App

Complete Example

App Lifecycle

Development Phase

Testing Phase

Launch Phase

Maintenance Mode

Best Practices

App Registration

Multi-Platform Support

App Management

Example: Versioning Strategy

Metadata Best Practices

Recommended Metadata Fields

Error Handling

Pagination Example

Integration with Other APIs

Achievements

Leaderboards

Products

Support