Overview

Introduction

This is the documentation for the Swat.io GraphQL Customer API. It allows customers to interact with Swat.io programmatically.

Technical Details

• URL:
  • Production: https://graphql.swatio.app/api
• Introspection: GraphQL Introspection is turned on. You can use tools like Postman, httpie or Bruno to generate type systems and documentation.
• Rate Limits: requests are rate-limited per user per minute. On 429-equivalent errors, respect the Retry-After / X-RateLimit-Reset values returned in the error payload (see Error responses).
• Timeouts: HTTP request and SQL timeouts are set to 30s/25s.

Minimum Recommended Headers:

Accept: application/json
Authorization: Bearer <token>
Content-Type: application/json

Example

Curl Request:

curl -s \
    -X POST \
    --location "https://graphql.swatio.app/api" \
    -H "content-type: application/json; charset=UTF-8" \
    -H "Authorization: Bearer <TOKEN>" \
    -d '{
          "query": "query whoAmI { me { id email first_name last_name } }",
          "variables": null
        }'

Response:

{
  "data": {
    "me": {
      "id": "1234",
      "email": "developer@example.com",
      "first_name": "Jane",
      "last_name": "Developer"
    }
  },
  "meta": {
    "x-swatio-trace-id": "abc123..."
  }
}

Error responses

All errors are returned with HTTP status 200 and a top-level errors array in the response body. Check this field, not the HTTP status, to detect failures.

Invalid or missing token:

{
  "errors": [
    {
      "message": "Unauthorized",
      "locations": [{ "line": 1, "column": 1 }],
      "path": ["me"],
      "extensions": {
        "code": "UNAUTHORIZED"
      }
    }
  ],
  "data": null,
  "meta": {
    "x-swatio-trace-id": "abc123..."
  }
}

Rate limit exceeded:

{
  "errors": [
    {
      "message": "Too many requests.",
      "locations": [{ "line": 3, "column": 21 }],
      "path": ["<query>"],
      "extensions": {
        "rateLimits": {
          "Retry-After": 18,
          "X-RateLimit-Reset": 1726565254,
          "X-Graphql-Endpoint": "<query>",
          "X-RateLimit-Limit": 100,
          "X-RateLimit-Remaining": 0
        }
      }
    }
  ],
  "data": null,
  "meta": {
    "x-swatio-trace-id": "abc123..."
  }
}

Back off until Retry-After (seconds) has passed or the X-RateLimit-Reset (unix timestamp) has been reached.

Validation error (e.g. invalid field value):

{
  "errors": [
    {
      "message": "Field 'publication_at' is invalid: must be a future date",
      "locations": [{ "line": 3, "column": 5 }],
      "path": ["postCreate"],
      "extensions": {
        "code": "VALIDATION_ERROR"
      }
    }
  ],
  "data": null,
  "meta": {
    "x-swatio-trace-id": "abc123..."
  }
}

Always include the x-swatio-trace-id value when reporting a bug to support.

Concepts

Core Entities

To understand how workflows are represented, it is necessary to understand these concepts:

• Organization: Represents a customer (sometimes called "group").
• Workspace: An organization can have multiple workspaces. It groups channels and team members (sometimes called "client").
• Channel: Represents a social media channel (Facebook page, Twitter user, etc.). Swat.io also supports "content planning" channels which are internal only.
• Post: A social media post. For some channel types like YouTube, videos are also called "posts".
• Asset: A media file (photo, video, document) stored in the workspace's library. Assets can be reused in multiple posts.

Client Compatibility

Our GraphQL API does not require a specific client. You can use curl, any programming language, or desktop applications like Bruno or Postman.

It is highly recommended to use desktop clients that support introspection for autocomplete and documentation.

Relevancy of x-swatio-trace-id

Every response returns a meta.x-swatio-trace-id field. If you report a bug, please always provide this trace ID to speed up analysis.

Time Format

The API uses ISO 8601 format: 2024-04-16T18:59:21+07:00.

How to…

Although the GraphQL introspection provides information about all queries, mutations, and types as well as their docs, it’s not easy to understand “how to” use them, as knowledge of the workflows within Swat.io is often necessary. This section gives a few common examples of how to work with the system.

User ID

Unlike workspace and channel IDs, the user ID cannot be read from the browser URL - it is only available via the API. Use the me query to retrieve the ID of the authenticated user:

curl -s \
    -X POST \
    --location "https://graphql.swatio.app/api" \
    -H "content-type: application/json; charset=UTF-8" \
    -H "Authorization: Bearer <TOKEN>" \
    -d '{"query":"query whoAmI { me { id email first_name last_name } }","variables":null}'

The returned id is the value to use wherever the API expects an assigned_user_id.

Workspace ID and Channel ID

To work with the API, one has to know several IDs to work with it, most commonly the “workspace ID” and one or more “channel IDs”.

Those IDs can be fetched with the clients query or deduced from when using the web application itself:

• the workspace ID Can be read from the browsers URL; here the workspace ID is 666

• the channel ID Relevant to fetch or create posts from a specific social media network. Here the channel IDs are 5555 and 7777