> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tổng quan GraphQL API

> Truy vấn các thao tác mạng xã hội được Ayrshare hỗ trợ thông qua một endpoint GraphQL duy nhất.

GraphQL API cung cấp một tập con được hỗ trợ của các khả năng REST của Ayrshare thông qua một endpoint duy nhất. Mỗi trường được cung cấp gọi cùng một controller bên dưới như phiên bản REST tương ứng, vì vậy xác thực, quyền sử dụng tính năng, hạn mức và dữ liệu phản hồi đều tuân theo hành vi của REST. REST vẫn là API đầy đủ hơn; hãy dùng schema hoặc Explorer để xem chính xác những thao tác nào GraphQL hỗ trợ.

Điều GraphQL mang lại là khả năng yêu cầu nhiều thứ trong một request và khám phá phạm vi GraphQL đang được hỗ trợ ngay từ chính schema, mà không cần đọc tài liệu từng trang một. Schema mô tả mọi trường request được hỗ trợ và các lựa chọn có kiểu (typed selection) sẵn có trên các phản hồi có cấu trúc; các thao tác trả về envelope REST dưới dạng `JSON` giữ nguyên toàn bộ payload đó.

```
https://api.ayrshare.com/graphql
```

Gửi một `POST` với body JSON chứa một `query`, giống hệt như với bất kỳ endpoint GraphQL nào. `GET` và `DELETE` trả về `405 Method Not Allowed` — truy vấn qua `GET` là tùy chọn trong đặc tả GraphQL và không được hỗ trợ tại đây.

<h2 id="your-first-query">
  Truy vấn đầu tiên của bạn
</h2>

```bash theme={"system"}
curl -X POST https://api.ayrshare.com/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ postHistory(lastDays: 7) }"}'
```

Phản hồi là cùng envelope JSON mà [endpoint lịch sử REST](/docs/apis/history/get-history) trả về, được bọc trong trường `data` của GraphQL:

```json theme={"system"}
{
  "data": {
    "postHistory": {
      "history": [
        { "id": "RkQ8uXg2jT7bNd1Wq0Ya", "status": "success", "post": "Hello world" }
      ],
      "refId": "9d2a7c41f0b8e6d35a1c",
      "count": 1,
      "lastUpdated": "2026-09-24T12:00:00.000Z",
      "nextUpdate": "2026-09-24T12:00:00.000Z"
    }
  }
}
```

<h2 id="asking-for-several-things-at-once">
  Yêu cầu nhiều thứ cùng lúc
</h2>

Lý do để dùng GraphQL là một request như thế này, vốn sẽ cần bốn lệnh gọi REST:

```graphql theme={"system"}
{
  history: postHistory(lastDays: 7)
  accounts: user
  comments: comments(id: "abc123")
  analytics: socialAnalytics(platforms: [INSTAGRAM])
}
```

Một lượt round trip trả về cả bốn. Lưu ý rằng đây là **bốn trường thao tác gốc và bốn lệnh gọi API cho mục đích tính phí**, không phải một. Việc chọn các trường phản hồi lồng nhau không làm tăng số lệnh gọi — xem [Giới hạn và Tính phí](/docs/apis/graphql/limits).

<h2 id="authentication">
  Xác thực
</h2>

Giống hệt REST. Gửi API key của bạn dưới dạng bearer token:

```
Authorization: Bearer YOUR_API_KEY
```

Nếu tài khoản của bạn sử dụng User Profile, các thao tác có cung cấp `profileKey` có thể chọn một profile theo một trong hai cách:

<ul class="custom-bullets">
  <li>Gửi <code>Profile-Key</code> làm giá trị mặc định cho toàn bộ request.</li>
  <li>Truyền <code>profileKey</code> trên từng trường riêng lẻ để ghi đè giá trị mặc định đó, cho phép một request thao tác trên nhiều profile.</li>
</ul>

Đối số của trường được ưu tiên khi cả hai cùng có mặt. Các trường ở cấp tài khoản hoặc chỉ dành cho tài khoản chính không cung cấp `profileKey` và có thể từ chối header `Profile-Key`; ví dụ, `createProfile` phải dùng API key chính mà không có header đó. Hãy kiểm tra định nghĩa schema của từng trường để biết phạm vi của nó, và xem [Quản lý nhiều người dùng](/docs/multiple-users/business-plan-overview) để biết cách profile key hoạt động.

<h2 id="try-it-without-writing-code">
  Thử mà không cần viết code
</h2>

[GraphQL Explorer](https://app.ayrshare.com/graphql-explorer) là một trình duyệt tương tác cho schema hiện tại. Nó liệt kê mọi thao tác GraphQL sẵn có cùng các đối số và mô tả, tự động hoàn thành khi bạn gõ, và chạy truy vấn trên tài khoản của bạn.

Bạn không cần API key để duyệt schema — schema là công khai, giống như tài liệu này. Bạn cần có API key để chạy truy vấn, vì mọi thao tác đều đi qua cùng cơ chế xác thực như REST.

<h2 id="should-you-use-graphql-or-rest">
  Bạn nên dùng GraphQL hay REST?
</h2>

REST vẫn là giao diện chính và là giao diện mà phần lớn tài liệu, [SDK](/docs/packages-guides/overview) và các tích hợp của chúng tôi được xây dựng xoay quanh. Hãy dùng GraphQL khi:

<ul class="custom-bullets">
  <li>Bạn cần nhiều mẩu dữ liệu không liên quan đến nhau và muốn lấy chúng trong một lượt round trip.</li>
  <li>Bạn muốn có tên thao tác, đối số, input object, enum và các lựa chọn phản hồi có kiểu mà máy có thể đọc được. Hầu hết phản hồi vẫn là <code>JSON</code> để giữ nguyên toàn bộ envelope REST; <code>createPost</code> hiện trả về <code>PostResult</code> có kiểu.</li>
  <li>Bạn đang khám phá API và muốn xem những gì hiện có mà không phải chuyển qua lại giữa các trang tài liệu.</li>
</ul>

Hãy tiếp tục dùng REST khi:

<ul class="custom-bullets">
  <li>Bạn đang tải tệp lên. Dữ liệu byte của media không thể truyền qua một request GraphQL — xem <a href="/docs/apis/graphql/using-the-api#uploading-media">Tải media lên</a> để biết cách được hỗ trợ.</li>
  <li>Bạn đang sử dụng một trong các <a href="/docs/packages-guides/overview">SDK hoặc tích hợp no-code</a> của chúng tôi, vốn giao tiếp bằng REST.</li>
  <li>Bạn muốn có ít phụ thuộc nhất có thể. Một lệnh gọi REST không cần gì ngoài một HTTP client.</li>
</ul>

Cả hai giao diện đều được hỗ trợ song song, và bạn có thể kết hợp chúng tùy ý trong cùng một tích hợp.

<h2 id="read-next">
  Đọc tiếp
</h2>

<ul class="custom-bullets">
  <li>[Sử dụng API](/docs/apis/graphql/using-the-api) — tìm thao tác, kiểu đối số và tải media lên.</li>
  <li>[Lỗi](/docs/apis/graphql/errors) — những lỗi nào thay đổi mã trạng thái HTTP, vì sao các thao tác thất bại vẫn trả về HTTP 200, và cách xử lý thành công một phần.</li>
  <li>[Giới hạn và Tính phí](/docs/apis/graphql/limits) — giới hạn kích thước truy vấn và cách tính số request.</li>
</ul>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.