> For the complete documentation index, see [llms.txt](https://www.xapijs.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.xapijs.dev/xapi-wrapper-library/state-resource.md).

# State Resource

## createState

Creates or merges into a state document by the agent, activity identifier and state identifier.

### **Example**

```typescript
const agent: Agent = {
  objectType: "Agent",
  name: "Test Agent",
  mbox: "mailto:test@agent.com"
};
const activityId: string = "https://example.com/activities/test-activity";
const stateId: string = activityId + "/states/myStateId";
const state: DocumentJson = {
  myKey: "myValue"
};

xapi.createState({
  agent: agent,
  activityId: activityId,
  stateId: stateId,
  state: state
});
```

### **Parameters**

| Parameter    | Type                                                                                                                            | Required | Description                                                  |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------ |
| agent        | [Agent](https://github.com/xapijs/xapi/tree/fd040c6f049f68fce317538626906de57ffebf44/src/interfaces/Statement/Actor/Agent.ts)   | true     | The agent experiencing the AU.                               |
| activityId   | string                                                                                                                          | true     | The URI of the activity.                                     |
| stateId      | string                                                                                                                          | true     | The URI of the state to be created or merged into.           |
| state        | [DocumentJson](https://github.com/xapijs/xapi/blob/d7eac9d07166df5c1f995e17a8ac98bbee99c548/src/resources/document/Document.ts) | true     | The state data to be stored.                                 |
| registration | string                                                                                                                          | false    | The registration associated with this state.                 |
| etag         | string                                                                                                                          | false    | The ETag of the original document if merging.                |
| matchHeader  | string                                                                                                                          | false    | The ETag header type. Accepts "If-Match" or "If-None-Match". |

### **Returns**

This method returns an `AxiosPromise`  with empty success `data` if successful.

## setState

Creates or overwrites a state document by the agent, activity identifier and state identifier.

### **Example**

```typescript
const agent: Agent = {
  objectType: "Agent",
  name: "Test Agent",
  mbox: "mailto:test@agent.com"
};
const activityId: string = "https://example.com/activities/test-activity";
const stateId: string = activityId + "/states/myStateId";
const state: Document = {
  myKey: "myValue"
};

xapi.setState(agent, activityId, stateId, state);
```

### **Parameters**

| Parameter    | Type                                                                                                                          | Required | Description                                                  |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------ |
| agent        | [Agent](https://github.com/xapijs/xapi/tree/fd040c6f049f68fce317538626906de57ffebf44/src/interfaces/Statement/Actor/Agent.ts) | true     | The agent experiencing the AU.                               |
| activityId   | string                                                                                                                        | true     | The URI of the activity.                                     |
| stateId      | string                                                                                                                        | true     | The URI of the state to be created or overwritten.           |
| state        | [Document](https://github.com/xapijs/xapi/blob/d7eac9d07166df5c1f995e17a8ac98bbee99c548/src/resources/document/Document.ts)   | true     | The state data to be stored.                                 |
| registration | string                                                                                                                        | false    | The registration associated with this state.                 |
| etag         | string                                                                                                                        | false    | The ETag of the original document if overwriting.            |
| matchHeader  | string                                                                                                                        | false    | The ETag header type. Accepts "If-Match" or "If-None-Match". |
| contentType  | string                                                                                                                        | false    | The content type of the state data.                          |

### **Returns**

This method returns an `AxiosPromise` with empty success `data` if successful.

## getStates

Gets an array of state identifiers by the agent and activity identifier.

### **Example**

```typescript
const agent: Agent = {
  objectType: "Agent",
  name: "Test Agent",
  mbox: "mailto:test@agent.com"
};
const activityId: string = "https://example.com/activities/test-activity";

xapi.getStates({
  agent: agent,
  activityId: activityId
}).then((result: AxiosResponse<string[]>) => {
  const states: string[] = result.data;
  console.log(states); // ["https://example.com/activities/test-activity/states/myStateId"]
});
```

### **Parameters**

| Parameter      | Type                                                                                                                          | Required | Description                                          |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------- |
| agent          | [Agent](https://github.com/xapijs/xapi/tree/fd040c6f049f68fce317538626906de57ffebf44/src/interfaces/Statement/Actor/Agent.ts) | true     | The agent experiencing the AU.                       |
| activityId     | string                                                                                                                        | true     | The URI of the activity.                             |
| registration   | string                                                                                                                        | false    | The registration associated with this state.         |
| since          | Timestamp                                                                                                                     | false    | Only return States stored since specified Timestamp. |
| useCacheBuster | boolean                                                                                                                       | false    | Enables cache busting.                               |

### **Returns**

This method returns an `AxiosPromise` with the success `data` containing an array of state identifiers if successful.

## getState

Gets a state document by the agent, activity identifier and the state identifier.

### **Example**

```typescript
const agent: Agent = {
  objectType: "Agent",
  name: "Test Agent",
  mbox: "mailto:test@agent.com"
};
const activityId: string = "https://example.com/activities/test-activity";
const stateId: string = activityId + "/states/myStateId";

xapi.getState({
  agent: agent,
  activityId: activityId,
  stateId: stateId
}).then((result: AxiosResponse<Document>) => {
  const state = result.data;
  // do stuff with state
});
```

### **Parameters**

| Parameter      | Type                                                                                                                          | Required | Description                                  |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------- |
| agent          | [Agent](https://github.com/xapijs/xapi/tree/fd040c6f049f68fce317538626906de57ffebf44/src/interfaces/Statement/Actor/Agent.ts) | true     | The agent experiencing the AU.               |
| activityId     | string                                                                                                                        | true     | The URI of the activity.                     |
| stateId        | string                                                                                                                        | true     | The URI of the state to be retrieved.        |
| registration   | string                                                                                                                        | false    | The registration associated with this state. |
| useCacheBuster | boolean                                                                                                                       | false    | Enables cache busting.                       |

### **Returns**

This method returns an `AxiosPromise` with the success `data` containing the stored [Document](https://github.com/xapijs/xapi/blob/d7eac9d07166df5c1f995e17a8ac98bbee99c548/src/resources/document/Document.ts) if successful.

## deleteState

Deletes a state document by the agent, activity identifier and the state identifier.

### **Example**

```typescript
const agent: Agent = {
  objectType: "Agent",
  name: "Test Agent",
  mbox: "mailto:test@agent.com"
};
const activityId: string = "https://example.com/activities/test-activity";
const stateId: string = activityId + "/states/myStateId";

xapi.deleteState({
  agent: agent,
  activityId: activityId,
  stateId: stateId
});
```

### **Parameters**

| Parameter    | Type                                                                                                                          | Required | Description                                  |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------- |
| agent        | [Agent](https://github.com/xapijs/xapi/tree/fd040c6f049f68fce317538626906de57ffebf44/src/interfaces/Statement/Actor/Agent.ts) | true     | The agent experiencing the AU.               |
| activityId   | string                                                                                                                        | true     | The URI of the activity.                     |
| stateId      | string                                                                                                                        | true     | The URI of the state to be deleted.          |
| registration | string                                                                                                                        | false    | The registration associated with this stage. |
| etag         | string                                                                                                                        | false    | The ETag of the original document.           |

### **Returns**

This method returns an `AxiosPromise` with empty success `data` if successful.

## deleteStates

Deletes all state documents by the agent and activity identifier.

### **Example**

```typescript
const agent: Agent = {
  objectType: "Agent",
  name: "Test Agent",
  mbox: "mailto:test@agent.com"
};
const activityId: string = "https://example.com/activities/test-activity";

xapi.deleteStates({
  agent: agent,
  activityId: activityId
});
```

### **Parameters**

| Parameter    | Type                                                                                                                          | Required | Description                                       |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------- |
| agent        | [Agent](https://github.com/xapijs/xapi/tree/fd040c6f049f68fce317538626906de57ffebf44/src/interfaces/Statement/Actor/Agent.ts) | true     | The agent experiencing the AU.                    |
| activityId   | string                                                                                                                        | true     | The URI of the activity.                          |
| registration | string                                                                                                                        | false    | The registration associated with this stage.      |
| etag         | string                                                                                                                        | false    | The ETag of the original document if overwriting. |

### **Returns**

This method returns an `AxiosPromise` with empty success `data` if successful.