# 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.


---

# 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/state-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.