API Documentation

Welcome to the GimCore API Guide. This guide provides detailed documentation on how to authenticate and interact with GimCore's dynamic applications, screens, issues (records), reports, and attachments.

These APIs are specifically optimized for Semantic Names, meaning developers and AI Agents can interact using human-readable names (e.g., department, tasks) instead of strict physical database IDs (cf123, 145).

Base URL

All API requests are made to the base URL:

https://{your-domain.com}/api/v1

Authentication

Every request requires an API Key for authentication. Pass your API Key in the HTTP headers using the X-API-KEY key.

X-API-KEY: your_generated_api_key_here

Note: All actions are performed under the context and permissions of the user associated with the given X-API-KEY.

1. App & Screen Resolving (Semantic Identifiers)

When an endpoint requires {appId} or {screenId}, you can flexibly provide either:

• Numeric ID: 15, 42
• Application/Screen Name: Quản lý công việc, Hóa đơn
• URL Slug / Function Name: tasks, invoice, payment_claim

The API backend will automatically resolve these strings to the correct ID.

2. Records Management (Issues)

Records (also known as Issues) are the dynamic data rows stored within a Screen (Form) in an App.

2.1. Search & Query Records

Fetch records based on dynamic criteria.

Endpoint: GET /apps/{appId}/screens/{screenId}/records

Query Parameters:

• fields (string): Comma-separated list of fields to return (e.g., id,fullname,department,age).
• conditions (string): SQL-like WHERE condition using InternalNames (e.g., department='IT' and age > 18). Supports {creator} and {assignee} placeholders.
• order (string): Sorting order (e.g., createdate desc).
• pageNo (int): Page number (default: 1).
• pageRow (int): Items per page (default: 50).

Example Request:

GET /api/v1/apps/qlcongviec/screens/tasks/records?fields=taskname,status&conditions=status='Doing'&pageNo=1&pageRow=20

2.2. Get Record by ID

Fetch all data of a single specific record.

Endpoint: GET /records/{recordId}

Example Response:

{
  "status": "success",
  "data": {
    "id": 1045,
    "taskname": "Fix API latency",
    "status": "Done"
  }
}

2.3. Create a New Record

Create a single record on a specific screen.

Endpoint: POST /apps/{appId}/screens/{screenId}/records

Payload: A JSON dictionary mapping InternalName or ColumnName to values.

Example Request (Creating an Invoice Claim via AI):

POST /api/v1/apps/finance/screens/payment_claim/records
Content-Type: application/json
{
  "invoice_number": "INV-2026-001",
  "vendor_name": "OpenAI Services",
  "total_amount": 5000,
  "currency": "USD"
}

2.4. Bulk Create Records

Create multiple records in a single transaction.

Endpoint: POST /apps/{appId}/screens/{screenId}/records/bulk

Payload: A JSON Array of dictionaries.

[
  { "taskname": "Task 1", "priority": "High" },
  { "taskname": "Task 2", "priority": "Low" }
]

2.5. Update Record (Full / Partial)

To update a record, you do not need the App/Screen IDs; just the recordId.

Full Update: PUT /records/{recordId}
Partial Update: PATCH /records/{recordId}

Example Request (Updating Status):

PATCH /api/v1/records/1045
Content-Type: application/json
{
  "status": "In Progress"
}

2.6. Delete Record

Marks a record as deleted.

Endpoint: DELETE /records/{recordId}

3. Attachments (File Upload)

Used for uploading files (e.g., OCR scanned documents, invoices) and attaching them to a specific record.

Endpoint: POST /records/{recordId}/attachments

Content-Type: multipart/form-data

Form Data Fields:

• file: (Binary File) The document/image to upload.
• fieldName: (String, Optional) The InternalName of the attachment field on the screen. (e.g., invoice_document, photo). GimCore will auto-increment the counter for this field.

Example Use Case (AI OCR Bot):

1. AI reads an invoice PDF.
2. AI calls POST /apps/finance/screens/payment_claim/records with extracted data. Result returns recordId: 512.
3. AI calls POST /records/512/attachments passing the PDF file and fieldName: "invoice_document".

4. Discovery & Reporting

4.1. Get App Reports

Discover and retrieve a list of all built-in reports/dashboards available in a specific application.

Endpoint: GET /apps/{appId}/reports

Example Response:

{
  "status": "success",
  "data": [
    {
      "id": 142,
      "reportName": "Chi phí hàng tháng",
      "url": "chi-phi-hang-thang",
      "viewUrl": "/apps/finance/chi-phi-hang-thang-142",
      "thumbnail": "/images/chart.png"
    }
  ]
}

4.2. Get Reports

Discover and retrieve a list of all built-in reports/dashboards available in a specific application.

Endpoint: GET /api/v1/reports

Example Response:

Query Parameter (Optional): You can pass the parameter 'q' to search for the name or description of the report.
Example: To find all revenue reports: GET /api/v1/reports?q=revenue
Return all (up to 50 most recent): GET /api/v1/reports

Note: The viewUrl provided is SEO-friendly and can be safely sent to end-users (e.g., via chatbot) to open the report directly in the browser.