# Statement Resource

## sendStatement

Sends a statement to the LRS.

### **Examples**

#### **Example 1: Send Basic Statement**

```typescript
import XAPI, { Statement } from "@xapi/xapi";

// new XAPI() etc

const myStatement: Statement = {
  actor: {
    objectType: "Agent",
    name: "Test Agent",
    mbox: "mailto:hello@example.com"
  },
  verb: {
    id: "http://example.com/verbs/tested",
    display: {
        "en-GB": "tested"
    }
  },
  object: {
    objectType: "Activity",
    id: "https://github.com/xapijs/xapi"
  }
};

xapi.sendStatement({
  statement: myStatement
});
```

#### **Example 2: Send Embedded Attachment Statement**

```typescript
import CryptoJS from "crypto-js";
import { arrayBufferToWordArray } from "...";

const attachmentContent: string = "hello world";
const arrayBuffer: ArrayBuffer = new TextEncoder().encode(attachmentContent);

const myStatement: Statement = {
  // actor, verb, object etc,
  attachments: [{
    usageType: XAPI.AttachmentUsages.SUPPORTING_MEDIA,
    display: {
        "en-US": "Text Attachment"
    },
    description: {
        "en-US": `The text attachment contains "${attachmentContent}"`
    },
    contentType: "text/plain",
    length: arrayBuffer.byteLength,
    sha2: CryptoJS.SHA256(arrayBufferToWordArray(arrayBuffer)).toString()
  }]
}

xapi.sendStatement({
  statement: myStatement,
  attachments: [arrayBuffer]
});
```

This example requires [CryptoJS](https://cryptojs.gitbook.io/docs/) to generate a sha2 of the attachment data and [convert the array buffer to a word array](https://github.com/xapijs/xapi/blob/d7eac9d07166df5c1f995e17a8ac98bbee99c548/test/arrayBufferToWordArray.ts).

### **Parameters**

| Parameter   | Type                                                                                                                            | Required | Description                                             |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------- |
| statement   | [Statement](https://github.com/xapijs/xapi/tree/fd040c6f049f68fce317538626906de57ffebf44/src/interfaces/Statement/Statement.ts) | true     | The statement you wish to send to the LRS.              |
| attachments | ArrayBuffer\[]                                                                                                                  | false    | An array of attachment data converted to `ArrayBuffer`. |

### **Returns**

This method returns an `AxiosPromise` with the success `data` containing a string array of statement IDs if successful, or if unsuccessful the rejection contains an error message.

## sendStatements

Sends multiple statements to the LRS.

#### **Example 1: Send Basic Statements**

```typescript
import XAPI, { Statement } from "@xapi/xapi";

// new XAPI() etc

const myStatement: Statement = {
  actor: {
    objectType: "Agent",
    name: "Test Agent",
    mbox: "mailto:hello@example.com"
  },
  verb: {
    id: "http://example.com/verbs/tested",
    display: {
        "en-GB": "tested"
    }
  },
  object: {
    objectType: "Activity",
    id: "https://github.com/xapijs/xapi"
  }
};

// Define another statement
const myStatementTwo: Statement = {
  ...myStatement
};

xapi.sendStatements({
  statements: [myStatement, myStatementTwo]
});
```

#### **Example 2: Send Embedded Attachment Statements**

```typescript
import CryptoJS from "crypto-js";
import { arrayBufferToWordArray } from "...";

const attachmentContent: string = "hello world";
const arrayBuffer: ArrayBuffer = new TextEncoder().encode(attachmentContent);

const myStatement: Statement = {
  // actor, verb, object etc,
  attachments: [{
    usageType: XAPI.AttachmentUsages.SUPPORTING_MEDIA,
    display: {
        "en-US": "Text Attachment"
    },
    description: {
        "en-US": `The text attachment contains "${attachmentContent}"`
    },
    contentType: "text/plain",
    length: arrayBuffer.byteLength,
    sha2: CryptoJS.SHA256(arrayBufferToWordArray(arrayBuffer)).toString()
  }]
}

// Define another statement
const myStatementTwo: Statement = {
  ...myStatement
};

// Send through the attachments in the same sequence as they
// appear in the statements, for brevity we are using the same
// attachment here twice

xapi.sendStatement({
  statements: [myStatement, myStatementTwo],
  attachments: [arrayBuffer, arrayBuffer]
});
```

This example requires [CryptoJS](https://cryptojs.gitbook.io/docs/) to generate a sha2 of the attachment data and [convert the array buffer to a word array](https://github.com/xapijs/xapi/blob/d7eac9d07166df5c1f995e17a8ac98bbee99c548/test/arrayBufferToWordArray.ts).

### **Parameters**

| Parameter   | Type                                                                                                                               | Required | Description                                             |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------- |
| statements  | [Statement](https://github.com/xapijs/xapi/tree/fd040c6f049f68fce317538626906de57ffebf44/src/interfaces/Statement/Statement.ts)\[] | true     | The statements you wish to send to the LRS.             |
| attachments | ArrayBuffer\[]                                                                                                                     | false    | An array of attachment data converted to `ArrayBuffer`. |

### **Returns**

This method returns an `AxiosPromise` with the success `data` containing a string array of statement IDs if successful, or if unsuccessful the rejection contains an error message.

## getStatement

To receive a single statement, you must use the `getStatement` method and pass the statement ID in the query. Optionally, you can provide additional parameters to the query to change the data format returned from the LRS.

### **Examples**

#### **Example 1: Get Basic Statement**

```typescript
xapi.getStatement({
  statementId: "abcdefgh-1234"
}).then((result: AxiosResponse<Statement>) => {
  const statement: Statement = result.data;
  // do stuff with `statement`
});
```

#### **Example 2: Get Embedded Attachment Statement**

```typescript
xapi.getStatement({
  statementId: "abcdefgh-1234",
  attachments: true
}).then((result: AxiosResponse<StatementResponseWithAttachments>) => {
  const parts: [Statement, ...Part[]] = result.data;
  const statement: Statement = parts[0];
  const attachment: unknown = parts[1];
})
```

### **Parameters**

| Parameter   | Type    | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| statementId | string  | true     | The identifier of the statement to request.                                                                                                                                                                                                                                                                                                                                                                                                      |
| attachments | boolean | false    | Whether to return the attachment(s) associated with the statement, if any.                                                                                                                                                                                                                                                                                                                                                                       |
| format      | string  | false    | <p>What human readable names and descriptions are included in the statement.</p><ul><li><code>exact</code> format returns the statements exactly as they were received by the LRS.</li><li><code>ids</code> only ids are returned with none of the human readable descriptions.</li><li><code>canonical</code> format requests the LRS to return its own internal definitions of objects, rather than those provided in the statement.</li></ul> |

### **Returns**

This method returns an `AxiosPromise` with the success `data` containing the [Statement](https://github.com/xapijs/xapi/tree/fd040c6f049f68fce317538626906de57ffebf44/src/interfaces/Statement/Statement.ts) of the supplied `statementId`.

When getting a statement with `attachments: true`, the success `data` is returned as an array. The first array item is of type `Statement`, and the following are of type `Part`  and are the attachments supplied with the statement.

## getStatements

To receive an array of statements based upon a query, you must use the `getStatements` method. See the [GetStatementsQuery](https://github.com/xapijs/xapi/tree/fd040c6f049f68fce317538626906de57ffebf44/src/interfaces/XAPI/GetStatementsQuery.ts) interface for a full list of ways to create your query.

### **Example**

```typescript
const myAgent: Agent = {...};

xapi.getStatements({
  agent: myAgent
}).then((result: AxiosResponse<StatementsResponse>) => {
  const statementsResponse: StatementsResponse = result.data;
  // do stuff with `statementsResponse.statements`
});
```

### **Parameters**

| Parameter           | Type                  | Required | Description                                                                         |
| ------------------- | --------------------- | -------- | ----------------------------------------------------------------------------------- |
| agent               | Agent                 | false    | The agent to filter the query by.                                                   |
| verb                | string                | false    | The verb identifier to filter the query by.                                         |
| activity            | string                | false    | The activity identifier to filter the query by.                                     |
| registration        | string                | false    | The registration to filter the query by.                                            |
| related\_activities | boolean               | false    | Whether to include any activity in the statement as part of the filter to query by. |
| related\_agents     | boolean               | false    | Whether to include any agent in the statement as part of the filter to query by.    |
| since               | Timestamp (ISOString) | false    | Filters only statements after the given Timestamp.                                  |
| until               | Timestamp (ISOString) | false    | Filters only statements before the given Timestamp.                                 |
| limit               | number                | false    | Number of statements to return.                                                     |
| ascending           | boolean               | false    | Determines whether to return the statements in ascending order.                     |
| attachments         | boolean               | false    | Determines whether to return the attachments for the resulting statements.          |

### **Returns**

This method returns an `AxiosPromise` with the success `data` containing a [StatementsResponse](https://github.com/xapijs/xapi/tree/fd040c6f049f68fce317538626906de57ffebf44/src/interfaces/XAPI/StatementsResponse.ts) object.

When getting statements with `attachments: true`, the success `data` is returned as an array. The first array item is of type `StatementsResponse`, and the following are of type `Part`  and are the attachments supplied with the statement.

## getMoreStatements

To be used in conjunction with `getStatements`. If the `more` property is populated on your initial request, more data is available. Send the value of the `more` property to this method to get the next page of statements.

### **Example**

```typescript
const myAgent: Agent = {...};

xapi.getStatements({
  agent: myAgent
}).then((result: AxiosReponse<StatementsResponse>) => {
  // data
  xapi.getMoreStatements({
    more: result.data.more
  }).then((result: AxiosResponse<StatementsResponse>) => {
    // more data
  });
});
```

### **Parameters**

| Parameter | Type   | Required | Description                                                                             |
| --------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| more      | string | true     | The `more` property passed from the `getStatements`/`getMoreStatements` query response. |

### **Returns**

This method returns an `AxiosPromise` with the success `data` containing a [StatementsResponse](https://github.com/xapijs/xapi/tree/fd040c6f049f68fce317538626906de57ffebf44/src/interfaces/XAPI/StatementsResponse.ts) object or an Array containing `StatementsResponse` and `Part` if the original query has `attachments: true`. When working in TypeScript you may need to cast your `result.data` return type explicitly as `StatementsResponse` or `StatementsResponseWithAttachments`.

## voidStatement

Voids a statement in the LRS by the supplied Actor.

### **Example**

```typescript
const actor: Actor = { ... };
xapi.voidStatement({
  actor: actor,
  statementId: "abcdefgh-1234"
});
```

**Parameters**

| Parameter   | Type                                                                                                                          | Required | Description                                                   |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------- |
| actor       | [Actor](https://github.com/xapijs/xapi/tree/fd040c6f049f68fce317538626906de57ffebf44/src/interfaces/Statement/Actor/Actor.ts) | true     | The Actor who is voiding the statement e.g. an administrator. |
| statementId | string                                                                                                                        | true     | The statement to be voided.                                   |

### **Returns**

This method returns an `AxiosPromise` with the success `data` containing an array of statement ID strings of the void statement.

## voidStatements

Voids multiple statements in the LRS by the supplied Actor.

### **Example**

```typescript
const actor: Actor = { ... };
xapi.voidStatements({
   actor: actor,
   statementIds: ["abcdefgh-1234", "ijklmnop-5678"]
});
```

**Parameters**

| Parameter    | Type                                                                                                                          | Required | Description                                                   |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------- |
| actor        | [Actor](https://github.com/xapijs/xapi/tree/fd040c6f049f68fce317538626906de57ffebf44/src/interfaces/Statement/Actor/Actor.ts) | true     | The Actor who is voiding the statement e.g. an administrator. |
| statementIds | string\[]                                                                                                                     | true     | The statements to be voided.                                  |

### **Returns**

This method returns an `AxiosPromise` with the success `data` containing an array of statement ID strings of the void statements.

## getVoidedStatement

To receive a single voided statement, you must use the `getVoidedStatement` method and pass the original statement ID in the query (not the original statement's void statement id). Optionally, you can provide additional parameters to the query to change the data format returned from the LRS.

### **Example**

```typescript
xapi.getVoidedStatement({
  statementId: "abcdefgh-1234"
}).then((result: AxiosResponse<Statement>) => {
  const voidStatement: Statement = result.data;
  // do stuff with `voidStatement`
});
```

### **Parameters**

| Parameter         | Type    | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ----------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| voidedStatementId | string  | true     | The identifier of the voided statement to request.                                                                                                                                                                                                                                                                                                                                                                                                      |
| attachments       | boolean | false    | Whether to return the attachment(s) associated with the voided statement, if any.                                                                                                                                                                                                                                                                                                                                                                       |
| format            | string  | false    | <p>What human readable names and descriptions are included in the voided statement.</p><ul><li><code>exact</code> format returns the statements exactly as they were received by the LRS.</li><li><code>ids</code> only ids are returned with none of the human readable descriptions.</li><li><code>canonical</code> format requests the LRS to return its own internal definitions of objects, rather than those provided in the statement.</li></ul> |

### **Returns**

This method returns an `AxiosPromise` with the success `data` containing the [Statement](https://github.com/xapijs/xapi/tree/fd040c6f049f68fce317538626906de57ffebf44/src/interfaces/Statement/Statement.ts) of the supplied `voidedStatementId`.

When getting a statement with `attachments: true`, the success `data` is returned as an array. The first array item is of type `Statement`, and the following are of type `Part`  and are the attachments supplied with the statement.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://www.xapijs.dev/xapi-wrapper-library/statement-resource.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.