API Documentation

Welcome to the GimCore REST API. This API provides a robust, enterprise-grade gateway for external integrations, mobile applications, and AI agents to interact with GimCore applications and data.

🔗 Base URL

All API requests must be prefixed with the following base URL:

https://{your-gimcore-domain}/api/v1

🔐 Authentication

GimCore uses a stateless API Key authentication mechanism. You must include your API Key in the HTTP headers of every request.

Header Format:

X-API-KEY: your_api_key_here

[!WARNING] Do not expose your API Key in client-side code (e.g., frontend JavaScript). Always route requests through a secure backend server.

🧭 1. Meta / Schema Discovery

These endpoints allow you to dynamically discover the Apps (Projects), Screens, and Field Schemas available to your API Key.

🏢 1.1. Get All Apps

Retrieves a list of all Apps (Projects) accessible to the authenticated user.

• Method: GET /apps
• Response:

  {
    "status": "success",
    "data": [
      {
        "appId": 10,
        "name": "HR Management",
        "description": "Human resources and leave requests"
      }
    ]
  }
  

📱 1.2. Get Screens in an App

Retrieves all configured Screens (Forms) belonging to a specific App.

• Method: GET /apps/{appId}/screens
• Response:

  {
    "status": "success",
    "data": [
      {
        "id": 55,
        "name": "Leave Request",
        "description": ""
      }
    ]
  }
  

📋 1.3. Get Screen Schema

Retrieves the exact physical schema and field definitions for a specific Screen. This is extremely useful for rendering dynamic forms or mapping data.

• Method: GET /apps/{appId}/screens/{screenId}/schema
• Response:

  {
    "status": "success",
    "data": {
      "appId": 10,
      "screenId": 55,
      "fields": [
        {
          "id": 120,
          "internalName": "cf123",
          "displayName": "Reason for Leave",
          "type": "textarea",
          "isRequired": true,
          "isReadOnly": false
        }
      ]
    }
  }
  

🗃️ 2. Record Management (CRUD)

These endpoints allow you to manipulate actual data records (Issues/Tasks) within a specific App and Screen.

✨ 2.1. Create a New Record

Creates a single record. The payload should be a flat JSON object where keys correspond to the internalName (e.g., cf123, title, status) from the Schema API.

• Method: POST /apps/{appId}/screens/{screenId}/records
• Request Body:

  {
    "title": "Annual Leave - John Doe",
    "status": "1",
    "cf123": "Taking a family vacation."
  }
  

• Response:

  {
    "status": "success",
    "message": "Created successfully",
    "recordId": 9876
  }
  

⚡ 2.2. Bulk Create Records

High-performance endpoint to insert multiple records at once. GimCore uses a "Best Effort" processing model: valid records will be inserted even if some fail.

• Method: POST /apps/{appId}/screens/{screenId}/records/bulk
• Request Body:

  [
    { "title": "Task 1", "status": "2" },
    { "title": "Task 2", "status": "1" }
  ]
  

• Response:

  {
    "status": "success",
    "total": 2,
    "success": 2,
    "failed": 0,
    "errors": []
  }
  

[!TIP] The Bulk Create API skips individual email notifications and heavy post-actions to ensure maximum throughput. Use this for importing CSV/Excel data.

📖 2.3. View a Record

Fetches the full data payload for a specific record. The response automatically joins custom fields.

• Method: GET /records/{recordId}
• Response:

  {
    "status": "success",
    "data": {
      "id": 9876,
      "title": "Annual Leave - John Doe",
      "status": "1",
      "cf123": "Taking a family vacation."
    }
  }
  

🔄 2.4. Full Update (PUT)

Replaces the data of an existing record. Fields not provided in the payload may be reset or evaluated against default workflow rules.

• Method: PUT /records/{recordId}
• Request Body:

  {
    "title": "Annual Leave - John Doe (Updated)",
    "status": "2"
  }
  

🎯 2.5. Partial Update (PATCH) - High Performance

Updates specific fields without affecting the rest of the record.

• Method: PATCH /records/{recordId}
• Request Body:

  {
    "status": "3"
  }
  

[!IMPORTANT] Performance Optimization: If your payload contains exactly one field (ignoring identifiers like id, issueId, etc.), GimCore will intelligently bypass the heavy workflow engine and execute a micro-query to update that single column directly in the database. This is the recommended approach for quick state changes (e.g., drag-and-drop Kanban operations).

🗑️ 2.6. Delete a Record

Performs a safe "Soft Delete" on the record, removing it from active views while preserving historical audit trails.

• Method: DELETE /records/{recordId}
• Response:

  {
    "status": "success",
    "message": "Record deleted successfully",
    "recordId": 9876
  }
  

🛡️ 3. Rate Limiting and Security

• 🚦 Rate Limit: 100 requests per minute per IP. Exceeding this will result in a 429 Too Many Requests response.
• 🧱 Data Isolation: Every API request dynamically evaluates the authenticated user's permissions. If an API Key attempts to access an appId or screenId they are not assigned to, a 403 Forbidden response is returned.