Documentation

Learn how to use Appship to optimize your App Store presence with AI-powered metadata generation.

Getting Started

Appship is an AI-powered App Store Optimization (ASO) platform that helps you generate compelling metadata and submit it directly to App Store Connect. Get started in minutes with our CLI or API.

Quick Start

Install and Login

bash

npx appship login

Enter your API key when prompted. Get your API key from the dashboard.

Add to Claude Code

bash

claude mcp add appship -- npx appship

This enables Appship tools in Claude Code for natural language control.

Start Generating

text

Claude: "Generate metadata for my fitness tracking app"

Authentication

Appship uses API keys for authentication. Your API key grants access to all API endpoints and MCP tools.

API Key Format

API keys follow the format: as_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Using Your API Key

CLI Authentication

bash

# Login with your API key
npx appship login

# Check current authentication
npx appship whoami

# Logout
npx appship logout

API Authentication

bash

curl -X GET https://appship.up.railway.app/api/user/me \
  -H "x-api-key: as_live_your_api_key_here"

Environment Variable

bash

# Set API key as environment variable
export APPSHIP_API_KEY=as_live_your_api_key_here

Security Note: Never share your API key publicly or commit it to version control. Use environment variables for secure storage.

MCP Integration

Appship integrates with Claude through the Model Context Protocol (MCP), allowing you to manage your apps using natural language.

Available Tools

get_user_infoFree

Get your account info, credit balance, and Apple connection status.

list_apple_appsFree

List all your apps connected from App Store Connect.

get_app_versionsFree

Get all versions for an app with their status (editable, live, etc.).

generate_metadata1 Credit

Generate AI-optimized title, subtitle, description, and keywords.

generate_whats_new1 Credit

Generate engaging release notes for app updates.

generate_keywords1 Credit

Generate ASO-optimized keywords (max 100 characters).

submit_metadata1 Credit

Submit metadata directly to App Store Connect.

Example Prompts

text

# Check your account
"What's my Appship credit balance?"

# List your apps
"Show me all my apps from App Store Connect"

# Generate metadata
"Generate metadata for my weather app. It shows hourly forecasts,
severe weather alerts, and has a beautiful widget."

# Submit to App Store
"Submit this metadata to App Store Connect for my app in English"

Generate Metadata

Generate ASO-optimized metadata using AI. Our system follows Apple's guidelines and best practices automatically.

API Endpoint

json

POST /api/generate/metadata

{
  "appName": "FitTrack Pro",
  "appDescription": "A fitness tracking app with workout plans,
                     nutrition logging, and progress photos",
  "locale": "en-US"
}

Response

json

{
  "title": "FitTrack Pro: Workout Planner",
  "subtitle": "Fitness Goals Made Simple",
  "description": "Transform your fitness journey with FitTrack Pro...",
  "keywords": "fitness,workout,exercise,training,gym,health",
  "promotionalText": "Start your 7-day free trial today!",
  "whatsNew": "Bug fixes and performance improvements"
}

Field Limits

Field	Max Length	Notes
Title	30 characters	App name + subtitle
Subtitle	30 characters	Brief tagline
Description	4,000 characters	Full app description
Keywords	100 characters	Comma-separated
Promotional Text	170 characters	Can be updated anytime
What's New	4,000 characters	Release notes

Submit to App Store

Submit your metadata directly to App Store Connect. Requires Apple API credentials to be configured.

Configure Apple Credentials

First, set up your App Store Connect API credentials:

json

PUT /api/user/apple-credentials

{
  "appleKeyId": "XXXXXXXXXX",
  "appleIssuerId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "applePrivateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
}

Submit Metadata

json

POST /api/apps/{appId}/submit-metadata

{
  "locale": "en-US",
  "platform": "IOS",
  "metadata": {
    "title": "FitTrack Pro: Workout Planner",
    "subtitle": "Fitness Goals Made Simple",
    "description": "Transform your fitness journey...",
    "keywords": "fitness,workout,exercise",
    "whatsNew": "New features and improvements"
  }
}

Note: If no editable version exists, Appship will automatically create a new version for you.

Multi-Locale Support

Generate and submit metadata in multiple languages to reach a global audience.

Supported Locales

en-US

en-GB

en-AU

fr-FR

de-DE

es-ES

it-IT

pt-BR

zh-Hans

zh-Hant

nl-NL

ar-SA

Generate for Multiple Locales

json

# Generate Turkish metadata
{
  "appName": "FitTrack Pro",
  "appDescription": "Fitness tracking app with workouts",
  "locale": "tr"
}

# Response will be in Turkish
{
  "title": "FitTrack Pro: Antrenman",
  "subtitle": "Fitness Hedeflerinize Ulaşın",
  "description": "FitTrack Pro ile fitness yolculuğunuzu...",
  ...
}

Credits & Billing

Appship uses a credit-based system. Each operation that uses AI or submits to App Store Connect costs 1 credit.

Credit Usage

Operation	Credits
Get user info	Free
List apps	Free
Get app versions	Free
Generate metadata	1 credit
Generate what's new	1 credit
Generate keywords	1 credit
Submit metadata	1 credit

Plans

Free

5 credits

On signup

Starter

50 credits

$19/month

Pro

500 credits

$99/month

Check Balance

json

GET /api/user/credits

Response:
{
  "credits": 42
}

API Reference

Complete API reference for direct integration.

Base URL

bash

https://appship.up.railway.app/api

Endpoints

GET/user/me

Get current user info and credit balance

GET/projects/apple-apps

List all apps from App Store Connect

GET/apps/:appId/versions

Get all versions for an app

POST/generate/metadata

Generate AI metadata (1 credit)

POST/generate/whats-new

Generate release notes (1 credit)

POST/generate/keywords

Generate keywords (1 credit)

POST/apps/:appId/submit-metadata

Submit metadata to App Store Connect (1 credit)

PUT/user/apple-credentials

Update Apple App Store Connect credentials

Error Responses

json

// 401 Unauthorized
{
  "error": "Invalid or missing API key"
}

// 402 Payment Required
{
  "error": "Insufficient credits",
  "credits": 0,
  "required": 1
}

// 400 Bad Request
{
  "error": "Validation error",
  "details": [...]
}

Need Help?

Can't find what you're looking for? We're here to help.

Contact Support GitHub Issues