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

# Core Concepts

> Actors, return-value conventions, yielding, and rate limits that apply to every method.

These rules apply to **every** method in the API Reference. Read this page once and the individual method pages will make a lot more sense.

## The actor object

Most write operations (ranking, logbook, points, sessions, webhooks) require an **actor** — the entity that is credited with performing the action. Actions taken through this API are audit-logged on the dashboard as "via in-game API" and attributed to this actor.

You can pass an actor in three forms:

<Tabs>
  <Tab title="Player (recommended)">
    Pass a `Player` instance directly. BloxCord reads the player's `UserId`, `Name`, and group rank automatically.

    ```lua theme={null}
    BloxCord:Invoke("setRank", targetUserId, "Promotion", 5, actingPlayer)
    ```
  </Tab>

  <Tab title="Table">
    Pass a table when the actor is not currently in the server.

    ```lua theme={null}
    local actor = {
        id = 123456789,       -- required, numeric UserId
        username = "Builderman",
        rank = 255,
        role = "Owner",
    }
    BloxCord:Invoke("setRank", targetUserId, "Promotion", 5, actor)
    ```
  </Tab>

  <Tab title="UserId">
    Pass a bare number or string when you only have an id.

    ```lua theme={null}
    BloxCord:Invoke("setRank", targetUserId, "Promotion", 5, 123456789)
    ```
  </Tab>
</Tabs>

<Warning>
  For every operation routed through the dashboard RPC (ranking, logbook, points, reputation, sessions, webhooks, batch), the actor **must resolve to a numeric UserId**. A table actor without a valid numeric `id` is rejected with a `400` error and the method returns `nil`.
</Warning>

<ParamField path="id" type="number | string" required>
  The actor's Roblox `UserId`. Must be numeric (1–20 digits).
</ParamField>

<ParamField path="username" type="string">
  The actor's display/username. Truncated to 40 characters server-side.
</ParamField>

<ParamField path="rank" type="number">
  The actor's group rank. Re-validated against the live group by the dashboard.
</ParamField>

<ParamField path="role" type="string">
  The actor's role name. Truncated to 120 characters server-side.
</ParamField>

## Return-value conventions

The value returned by `:Invoke()` depends on the method, but follows consistent patterns:

| Return style      | Meaning                                                                           |
| ----------------- | --------------------------------------------------------------------------------- |
| `boolean`         | `true` = success, `false` = failure or a business-rule rejection (e.g. cooldown). |
| `table` / `array` | The requested data. Read-only snapshots.                                          |
| `number`          | A scalar value such as a points balance.                                          |
| `nil`             | The backend was unreachable, timed out, or rejected the request.                  |

<Note>
  Because a failed network request generally surfaces as `nil` or `false`, always guard the return value before using it:

  ```lua theme={null}
  local balance = BloxCord:Invoke("getUserPoints", actor, player)
  if balance == nil then
      warn("Points lookup failed")
      return
  end
  ```
</Note>

## Yielding

Nearly every method performs an HTTPS request and **yields** the calling thread until the backend responds (or the request times out). Guidelines:

* Never call these methods on `RunService.Heartbeat`, `Stepped`, or `RenderStepped`.
* Wrap independent calls in `coroutine.wrap` / `task.spawn` if you need concurrency.
* Expect occasional `nil` returns during network hiccups and handle them.

## Rate limits

Operations that route through the dashboard RPC layer share a per-server budget:

<ParamField path="Operations / minute" type="120">
  Combined across single and batch calls, per game server. Exceeding this returns `nil` (HTTP `429`).
</ParamField>

<ParamField path="Batch size" type="20">
  The maximum number of operations in a single [`apiBatch`](/reference/webhooks-batch#apibatch) call.
</ParamField>

Some methods add their own limits (for example, [`modcall`](/reference/moderation#modcall) enforces a 10-minute per-player cooldown). These are noted on the relevant method.

## Invalid methods

Calling `:Invoke()` with an unknown method name emits a warning to the server console and returns `false`. Double-check spelling and casing — method names are **case-sensitive**.