Skip to content

n8n_api_documentation.md

Latest commit

 

History

History
565 lines (415 loc) · 10.5 KB

n8n_api_documentation.md

File metadata and controls

565 lines (415 loc) · 10.5 KB

Tài liệu API n8n

Giới thiệu

n8n cung cấp REST API cho phép bạn tương tác với hệ thống một cách lập trình. Tài liệu này tổng hợp các API có sẵn trong n8n và cách sử dụng chúng.

Xác thực (Authentication)

n8n sử dụng API key để xác thực các cuộc gọi API.

Tạo API key

  1. Đăng nhập vào n8n
  2. Đi đến Settings > n8n API
  3. Chọn "Create an API key"
  4. Sao chép "My API Key" để sử dụng trong các cuộc gọi API

Sử dụng API key

Gửi API key trong header X-N8N-API-KEY của mỗi request.

curl -X 'GET' \
  '<N8N_HOST>:<N8N_PORT>/<N8N_PATH>/api/v1/workflows' \
  -H 'accept: application/json' \
  -H 'X-N8N-API-KEY: <your-api-key>'

Xóa API key

  1. Đăng nhập vào n8n
  2. Đi đến Settings > n8n API
  3. Chọn "Delete" bên cạnh key bạn muốn xóa
  4. Xác nhận xóa bằng cách chọn "Delete Forever"

Phân trang (Pagination)

Kích thước trang mặc định là 100 kết quả, tối đa là 250.

Khi phản hồi chứa nhiều hơn một trang, nó sẽ bao gồm giá trị nextCursor, bạn có thể sử dụng để yêu cầu các trang tiếp theo.

# Lấy trang đầu tiên
curl -X 'GET' \
  '<N8N_HOST>:<N8N_PORT>/<N8N_PATH>/api/v1/workflows?limit=150' \
  -H 'accept: application/json' \
  -H 'X-N8N-API-KEY: <your-api-key>'

# Phản hồi sẽ bao gồm nextCursor
{
  "data": [...],
  "nextCursor": "MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA"
}

# Lấy trang tiếp theo
curl -X 'GET' \
  '<N8N_HOST>:<N8N_PORT>/<N8N_PATH>/api/v1/workflows?limit=150&cursor=MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA' \
  -H 'accept: application/json' \
  -H 'X-N8N-API-KEY: <your-api-key>'

Danh sách API

1. API Người dùng (User)

Lấy tất cả người dùng

GET /api/v1/users

Tham số truy vấn:

  • limit (số, tối đa 250, mặc định 100): Số lượng kết quả tối đa trả về
  • cursor (chuỗi): Dùng cho phân trang
  • includeRole (boolean, mặc định false): Có bao gồm vai trò của người dùng hay không
  • projectId (chuỗi): ID dự án để lọc người dùng

Tạo nhiều người dùng

POST /api/v1/users

Body request (mảng các đối tượng):

[
  {
    "email": "user@example.com",
    "role": "global:admin"
  }
]

Lấy người dùng theo ID/Email

GET /api/v1/users/{id}

Tham số đường dẫn:

  • id (chuỗi): ID hoặc email của người dùng

Tham số truy vấn:

  • includeRole (boolean, mặc định false): Có bao gồm vai trò của người dùng hay không

Xóa người dùng

DELETE /api/v1/users/{id}

Tham số đường dẫn:

  • id (chuỗi): ID hoặc email của người dùng

Thay đổi vai trò của người dùng

PATCH /api/v1/users/{id}/role

Tham số đường dẫn:

  • id (chuỗi): ID hoặc email của người dùng

Body request:

{
  "newRoleName": "global:admin"
}

2. API Kiểm toán (Audit)

Tạo báo cáo kiểm toán bảo mật

POST /api/v1/audit

Body request (tùy chọn):

{
  "additionalOptions": {
    "daysAbandonedWorkflow": 30,
    "categories": []
  }
}

3. API Thực thi (Execution)

Lấy tất cả các thực thi

GET /api/v1/executions

Tham số truy vấn:

  • includeData (boolean): Có bao gồm dữ liệu chi tiết của thực thi hay không
  • status (chuỗi, enum: "error", "success", "waiting"): Trạng thái để lọc các thực thi
  • workflowId (chuỗi): Workflow để lọc các thực thi
  • projectId (chuỗi): ID dự án để lọc các thực thi
  • limit (số, tối đa 250, mặc định 100): Số lượng kết quả tối đa trả về
  • cursor (chuỗi): Dùng cho phân trang

Lấy một thực thi cụ thể

GET /api/v1/executions/{id}

Tham số đường dẫn:

  • id (số): ID của thực thi

Tham số truy vấn:

  • includeData (boolean): Có bao gồm dữ liệu chi tiết của thực thi hay không

Xóa một thực thi

DELETE /api/v1/executions/{id}

Tham số đường dẫn:

  • id (số): ID của thực thi

4. API Workflow

Tạo workflow

POST /api/v1/workflows

Body request:

{
  "name": "Workflow 1",
  "nodes": [],
  "connections": {
    "main": []
  },
  "settings": {
    "saveExecutionProgress": true,
    "saveManualExecutions": true,
    "saveDataErrorExecution": "all",
    "saveDataSuccessExecution": "all",
    "executionTimeout": 3600,
    "timezone": "America/New_York"
  },
  "staticData": {}
}

Lấy tất cả workflow

GET /api/v1/workflows

Tham số truy vấn:

  • active (boolean): Lọc theo trạng thái hoạt động
  • tags (chuỗi): Lọc theo tags (phân tách bằng dấu phẩy)
  • name (chuỗi): Lọc theo tên
  • projectId (chuỗi): Lọc theo ID dự án
  • excludePinnedData (boolean): Không lấy dữ liệu đã ghim
  • limit (số, tối đa 250, mặc định 100): Số lượng kết quả tối đa trả về
  • cursor (chuỗi): Dùng cho phân trang

Lấy một workflow cụ thể

GET /api/v1/workflows/{id}

Tham số đường dẫn:

  • id (chuỗi): ID của workflow

Tham số truy vấn:

  • excludePinnedData (boolean): Không lấy dữ liệu đã ghim

Xóa một workflow

DELETE /api/v1/workflows/{id}

Tham số đường dẫn:

  • id (chuỗi): ID của workflow

Cập nhật một workflow

PUT /api/v1/workflows/{id}

Tham số đường dẫn:

  • id (chuỗi): ID của workflow

Body request:

{
  "name": "Workflow 1 Updated",
  "nodes": [],
  "connections": {
    "main": []
  },
  "settings": {
    "saveExecutionProgress": true,
    "saveManualExecutions": true,
    "saveDataErrorExecution": "all",
    "saveDataSuccessExecution": "all",
    "executionTimeout": 3600,
    "timezone": "America/New_York"
  },
  "staticData": {}
}

Kích hoạt một workflow

POST /api/v1/workflows/{id}/activate

Tham số đường dẫn:

  • id (chuỗi): ID của workflow

Vô hiệu hóa một workflow

POST /api/v1/workflows/{id}/deactivate

Tham số đường dẫn:

  • id (chuỗi): ID của workflow

Chuyển workflow sang dự án khác

PUT /api/v1/workflows/{id}/transfer

Tham số đường dẫn:

  • id (chuỗi): ID của workflow

Body request:

{
  "destinationProjectId": "VmwOO9HeTEj20kxM"
}

Lấy tags của workflow

GET /api/v1/workflows/{id}/tags

Tham số đường dẫn:

  • id (chuỗi): ID của workflow

Cập nhật tags của workflow

PUT /api/v1/workflows/{id}/tags

Tham số đường dẫn:

  • id (chuỗi): ID của workflow

Body request (mảng các đối tượng):

[
  {
    "id": "2tUt1wbLX592XDdX"
  }
]

5. API Thông tin xác thực (Credential)

Tạo thông tin xác thực

POST /api/v1/credentials

Body request:

{
  "name": "Joe's Github Credentials",
  "type": "github",
  "data": {
    "token": "ada612vad6fa5df4adf5a5dsf4389adsf76da7s"
  }
}

Xóa thông tin xác thực

DELETE /api/v1/credentials/{id}

Tham số đường dẫn:

  • id (chuỗi): ID của thông tin xác thực

Hiển thị schema dữ liệu thông tin xác thực

GET /api/v1/credentials/schema/{credentialTypeName}

Tham số đường dẫn:

  • credentialTypeName (chuỗi): Tên loại thông tin xác thực

Chuyển thông tin xác thực sang dự án khác

PUT /api/v1/credentials/{id}/transfer

Tham số đường dẫn:

  • id (chuỗi): ID của thông tin xác thực

Body request:

{
  "destinationProjectId": "VmwOO9HeTEj20kxM"
}

6. API Tags

Tạo tag

POST /api/v1/tags

Body request:

{
  "name": "Production"
}

Lấy tất cả tags

GET /api/v1/tags

Tham số truy vấn:

  • limit (số, tối đa 250, mặc định 100): Số lượng kết quả tối đa trả về
  • cursor (chuỗi): Dùng cho phân trang

Lấy một tag cụ thể

GET /api/v1/tags/{id}

Tham số đường dẫn:

  • id (chuỗi): ID của tag

Xóa một tag

DELETE /api/v1/tags/{id}

Tham số đường dẫn:

  • id (chuỗi): ID của tag

Cập nhật một tag

PUT /api/v1/tags/{id}

Tham số đường dẫn:

  • id (chuỗi): ID của tag

Body request:

{
  "name": "Production-Updated"
}

7. API Kiểm soát nguồn (Source Control)

Kéo thay đổi từ kho lưu trữ từ xa

POST /api/v1/source-control/pull

Body request:

{
  "force": true,
  "variables": {
    "foo": "bar"
  }
}

8. API Biến (Variables)

Tạo biến

POST /api/v1/variables

Body request:

{
  "key": "API_KEY",
  "value": "test-value"
}

Lấy tất cả biến

GET /api/v1/variables

Tham số truy vấn:

  • limit (số, tối đa 250, mặc định 100): Số lượng kết quả tối đa trả về
  • cursor (chuỗi): Dùng cho phân trang

Xóa một biến

DELETE /api/v1/variables/{id}

Tham số đường dẫn:

  • id (chuỗi): ID của biến

9. API Dự án (Projects)

Tạo dự án

POST /api/v1/projects

Body request:

{
  "name": "My Project"
}

Lấy tất cả dự án

GET /api/v1/projects

Tham số truy vấn:

  • limit (số, tối đa 250, mặc định 100): Số lượng kết quả tối đa trả về
  • cursor (chuỗi): Dùng cho phân trang

Xóa một dự án

DELETE /api/v1/projects/{projectId}

Tham số đường dẫn:

  • projectId (chuỗi): ID của dự án

Cập nhật một dự án

PUT /api/v1/projects/{projectId}

Tham số đường dẫn:

  • projectId (chuỗi): ID của dự án

Body request:

{
  "name": "My Project Updated"
}

Sử dụng API Playground (chỉ dành cho n8n tự host)

n8n cung cấp giao diện Swagger UI playground trong các phiên bản tự host. Đây là tài liệu tương tác, nơi bạn có thể thử nghiệm các request.

Đường dẫn để truy cập playground phụ thuộc vào cách bạn host n8n:

N8N_HOST:N8N_PORT/N8N_PATH/api/v1/docs

Lưu ý: Nếu bạn chọn "Authorize" và nhập API key của bạn trong API playground, bạn sẽ có quyền truy cập vào dữ liệu thực của mình. Điều này hữu ích để thử nghiệm các request, nhưng hãy lưu ý rằng bạn có thể thay đổi hoặc xóa dữ liệu thực.