Template tips:

• Content for template API Documentation & SDK Guides.

• In our template we use the Page Properties below as custom placeholders. Before exporting this content we set the Page Properties macro to “Hide from view“ to avoid it appearing in the export.

  • If the Page Properties table is something you need visible in your Confluence page you can also hide it as part of our Export Properties. In the Export Dialog you can go to Settings -> Advanced mode → Macros → Show page properties macro and toggle the setting off.

• In addition to this, some of our content leverages the macros of Scroll Exporter Extensions

  • This panel is wrapped in a Scroll Ignore which prevents it from appearing in the export.

Introduction

Welcome to the Good Software API documentation.

Our RESTful API is designed to give developers, partners, and system integrators a simple yet powerful way to interact with the Good Software platform. Using this API, you can seamlessly integrate core functionality into your own applications, automate recurring workflows, and extend the platform with custom features tailored to your business needs.

The API follows standard REST conventions and communicates using JSON, making it easy to work with from virtually any modern programming language. To help accelerate development, we provide officially supported SDKs in JavaScript, Python, and Java.

You can connect to either the Production environment for live data, or the Sandbox environment for safe experimentation and testing without impacting real users:

• Base URL (Production): https://api.goodsoftware.io/v1

• Base URL (Sandbox): https://sandbox.goodsoftware.io/v1

Getting Started

Before you make your first API call, ensure you have the following prerequisites:

API key – generated in your Good Software dashboard under Developer Settings.

Basic knowledge of REST and JSON – most endpoints require standard HTTP methods (GET, POST, PATCH, DELETE) and return data in JSON format.

Installed SDK (optional) – while you can interact with the API using raw HTTP requests, our SDKs provide ready-to-use functions, making integration faster and less error-prone.

Here’s a simple example using curl to list users from your account:

curl -X GET "https://api.goodsoftware.io/v1/users" \
     -H "Authorization: Bearer YOUR_API_KEY"

If your API key is valid, you will receive a JSON response containing a list of users. This confirms your authentication and ensures your environment is set up correctly.

Authentication & Security

The Good Software API uses Bearer Token Authentication. Every request must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

• Token Lifetime: 24 hours (after which you must generate or refresh your key).

• Scopes:

  • read → Grants read-only access to resources.

  • write → Allows creating, updating, and deleting resources in addition to reading.

  • admin → Grants full access, including user and account management.

Security Best Practices

• Store your API key securely in environment variables or a secrets manager.

• Never expose your API key in client-side code, public repositories, or shared logs.

• Rotate keys periodically and revoke keys that are no longer in use.

Rate Limits

To ensure fair usage and system stability, the API enforces rate limits based on your subscription plan:

• Free Tier: 100 requests per minute

• Pro Tier: 1,000 requests per minute

• Enterprise Tier: 5,000 requests per minute

If you exceed your limit, the API will temporarily block additional requests and respond with a 429 Too Many Requests error:

{
  "error": "Rate limit exceeded. Try again in 60 seconds."
}

Most responses also include rate limit headers such as:

• X-RateLimit-Limit → Your maximum requests per minute

• X-RateLimit-Remaining → Requests remaining in the current window

• X-RateLimit-Reset → Time (in seconds) until the limit resets

By monitoring these headers, you can implement smart retry logic and avoid unnecessary request failures.

Error Handling

Common error responses:

API Endpoint Reference

Users

Get All Users

• Endpoint: GET /users

• Description: Returns a paginated list of users

Request Example:

curl -X GET "https://api.goodsoftware.io/v1/users?page=1&limit=10" \
     -H "Authorization: Bearer YOUR_API_KEY"

Response Example:

{
  "page": 1,
  "limit": 10,
  "total": 250,
  "users": [
    {
      "id": "usr_001",
      "name": "Alice Johnson",
      "email": "alice@goodsoftware.io",
      "status": "active"
    },
    {
      "id": "usr_002",
      "name": "Bob Smith",
      "email": "bob@goodsoftware.io",
      "status": "inactive"
    }
  ]
}

Create a User

• Endpoint: POST /users

• Description: Creates a new user account

Request Example (JSON):

{
  "name": "Charlie Davis",
  "email": "charlie@goodsoftware.io",
  "role": "editor"
}

Response Example:

{
  "id": "usr_101",
  "name": "Charlie Davis",
  "email": "charlie@goodsoftware.io",
  "role": "editor",
  "status": "active",
  "created_at": "2025-08-18T10:15:30Z"
}

Code Snippets (SDK Examples)

JavaScript (Node.js)

import GoodSoftware from "goodsoftware-sdk";

const client = new GoodSoftware("YOUR_API_KEY");

// Fetch all users
client.users.list({ page: 1, limit: 5 })
  .then(response => console.log(response.users))
  .catch(error => console.error(error));

Python

from goodsoftware_sdk import Client

client = Client(api_key="YOUR_API_KEY")

# Create a new user
user = client.users.create(
    name="Dana Wright",
    email="dana@goodsoftware.io",
    role="viewer"
)
print(user)

Sample Workflow

Use Case: Create a User and Assign to a Project

sequenceDiagram
    participant Dev
    participant API
    participant Project

    Dev->>API: POST /users
    API-->>Dev: User Created (usr_101)
    Dev->>API: POST /projects/123/assign { "user_id": "usr_101" }
    API-->>Dev: Assignment Successful
    Project-->>Dev: User now part of project

Performance & Tuning

When building high-volume integrations with the Good Software API, it’s important to optimize for both speed and reliability. The following techniques help you reduce latency, handle larger datasets efficiently, and prevent unnecessary retries.

Batch Requests

For scenarios involving large data imports, use the dedicated bulk endpoint instead of sending multiple individual requests.

• Endpoint: POST /bulk/users

• Limit: Up to 1,000 users per request

• Use Case: Ideal for onboarding new users in bulk, syncing external databases, or migrating accounts.

Bulk requests reduce network overhead and significantly improve throughput. However, note that if a single record in the batch fails validation, the response will include details for the failed items so you can retry selectively.

Pagination

Most list endpoints return results in a paginated format to prevent timeouts and large payloads. Always use pagination parameters to control the size of responses:

• ?page=<number> – The page index (default: 1)

• ?limit=<number> – The number of results per page (default: 20, max: 100)

Example:

GET /users?page=2&limit=50

Response structure typically includes metadata for easier navigation:

{
  "data": [ ... ],
  "meta": {
    "page": 2,
    "per_page": 50,
    "total_pages": 10,
    "total_items": 500
  }
}

SDK-Specific Guidance

• Install (JavaScript): npm install goodsoftware-sdk

• Install (Python): pip install goodsoftware-sdk

• Install (Java):

<dependency>
  <groupId>io.goodsoftware</groupId>
  <artifactId>sdk</artifactId>
  <version>1.0.0</version>
</dependency>

Glossary

Understanding the key terms used throughout this documentation will help you work more effectively with the Good Software API and SDKs.

• User ID (usr_xxx)
  A unique identifier automatically assigned to each user in the system.

  • Format: usr_12345

  • Used in endpoints such as GET /users/{user_id}

  • Immutable once created.

• Project ID (prj_xxx)
  Identifier for project objects within Good Software.

  • Format: prj_67890

  • Required when retrieving, updating, or deleting project-specific data.

  • Useful for scoping API operations to a single project.

• Bearer Token
  A security token that authenticates your API requests.

  • Passed in the Authorization header:

    Authorization: Bearer YOUR_API_KEY
    
    

  • Tokens expire after 24 hours and must be refreshed or regenerated.

  • Should always be kept private and never exposed in client-side code.

• Scope
  Defines what actions your API key can perform.

  • read → Read-only access (safe for dashboards and reporting).

  • write → Read, create, update, and delete resources.

  • admin → Full access, including user and system management.

  • Multiple scopes may be combined depending on the key.

• Sandbox Environment
  A test environment (https://sandbox.goodsoftware.io/v1) that allows developers to safely experiment without affecting production data.

• Rate Limit
  The maximum number of requests allowed per minute, based on your subscription tier (Free, Pro, Enterprise). Exceeding this returns a 429 Too Many Requests error.

• Pagination
  A mechanism for retrieving large result sets in smaller chunks using ?page and ?limit query parameters. Ensures faster responses and reduces server load.

• Webhook (if used)
  A callback mechanism that allows Good Software to notify your application in real-time about specific events (e.g., user.created, project.updated).

• SDK (Software Development Kit)
  Prebuilt client libraries (JavaScript, Python, Java) that wrap API calls into easier-to-use methods, speeding up integration. Example Java dependency:

  <dependency>
    <groupId>io.goodsoftware</groupId>
    <artifactId>sdk</artifactId>
    <version>1.0.0</version>
  </dependency>
  
  

Support

We want to ensure you have everything you need to successfully build with the Good Software API. If you encounter issues, have questions, or want to share feedback, the following support channels are available:

• Email Support
  support@goodsoftware.io

  • Recommended for account-specific or technical issues that require direct assistance.

  • Our support team typically responds within 24 business hours (faster for Pro and Enterprise plans).

  • Include your API key (masked), request ID, or error details when contacting us to speed up troubleshooting.

• Community Forum
  https://community.goodsoftware.io

  • A space where developers, partners, and system integrators share best practices, common solutions, and code snippets.

  • Browse FAQs, ask technical questions, and learn from others who are integrating with the API.

  • Monitored by both Good Software engineers and community experts.

• API Status Page
  https://status.goodsoftware.io

  • Provides real-time visibility into API uptime, response times, and incident history.

  • Subscribe to status alerts via email or RSS to be notified of outages or maintenance windows.

  • Check here first if you experience unexpected downtime or slow responses.

Appendix

Full Error Codes List

{
  "400": "Bad Request",
  "401": "Unauthorized",
  "403": "Forbidden",
  "404": "Not Found",
  "409": "Conflict",
  "429": "Too Many Requests",
  "500": "Internal Server Error"
}

Changelog

• v1.0.0 – Initial release (Users, Projects, Authentication)

• v1.1.0 – Added Bulk Import endpoints

• v1.2.0 – SDKs released for Node.js, Python, Java