---
agentTools:
  projectIndex: https://hermae.readme.io/llms.txt
---

# Upsert a Source

This endpoint manages training sources, the primary components for shaping the AI's knowledge space. Sources represent individual pieces of training data, essential for refining the AI's understanding. Any content saved will be able to be recalled. 

The `key` field acts as an identifier for this source. If a source already exists with the passed `key` value, the existing source will be overwritten. If an existing source with that key does not exist, a new source will be created.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "version": "1.2.1",
    "title": "Hermae API",
    "description": "API for managing the Hermae application."
  },
  "servers": [
    {
      "url": "https://api.hermae.com"
    }
  ],
  "security": [
    {
      "HermaeKeyAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "HermaeKeyAuth": {
        "type": "apiKey",
        "name": "x-hermae-key",
        "in": "header",
        "description": "Your API key for authentication."
      }
    },
    "schemas": {
      "OrganizationID": {
        "type": "string",
        "example": "A1B2C3D4E6"
      },
      "SpaceID": {
        "type": "string",
        "example": "A1B2C3D4E6"
      }
    },
    "parameters": {
      "OrganizationID": {
        "schema": {
          "$ref": "#/components/schemas/OrganizationID"
        },
        "required": true,
        "name": "organizationId",
        "in": "path"
      },
      "SpaceID": {
        "schema": {
          "$ref": "#/components/schemas/SpaceID"
        },
        "required": true,
        "name": "spaceId",
        "in": "path"
      }
    }
  },
  "paths": {
    "/organizations/{organizationId}/spaces/{spaceId}/sources": {
      "post": {
        "summary": "Upsert a Source",
        "description": "This endpoint manages training sources, the primary components for shaping the AI's knowledge space. Sources represent individual pieces of training data, essential for refining the AI's understanding. Any content saved will be able to be recalled. \n\nThe `key` field acts as an identifier for this source. If a source already exists with the passed `key` value, the existing source will be overwritten. If an existing source with that key does not exist, a new source will be created.",
        "tags": [
          "Sources"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/OrganizationID"
          },
          {
            "$ref": "#/components/parameters/SpaceID"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "key": {
                    "type": "string",
                    "maxLength": 256,
                    "description": "Unique identifier for this information that is consistent across updates."
                  },
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Source page URL, where user can find more information."
                  },
                  "content": {
                    "type": "string",
                    "maxLength": 100000,
                    "description": "Content of the source. Encrypted at rest."
                  },
                  "title": {
                    "type": "string",
                    "maxLength": 64,
                    "description": "Title of the content."
                  },
                  "origin": {
                    "type": "string",
                    "maxLength": 16,
                    "description": "A string representing where this exchange originates from."
                  },
                  "metadata": {
                    "type": "object",
                    "additionalProperties": {
                      "anyOf": [
                        {
                          "type": "string",
                          "maxLength": 128
                        },
                        {
                          "type": "number"
                        },
                        {
                          "type": "boolean"
                        }
                      ]
                    }
                  }
                },
                "required": [
                  "key",
                  "content",
                  "title",
                  "origin"
                ],
                "description": "An object representing a document used for training."
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The newly created source document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "number"
                    },
                    "returns": {
                      "type": "object",
                      "properties": {
                        "source": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "key": {
                                "type": "string",
                                "maxLength": 256,
                                "description": "Unique identifier for this information that is consistent across updates."
                              },
                              "title": {
                                "type": "string",
                                "maxLength": 64,
                                "description": "Title of the content."
                              },
                              "content": {
                                "type": "string",
                                "maxLength": 100000,
                                "description": "Content of the source. Encrypted at rest."
                              },
                              "content_iv": {
                                "type": "string",
                                "description": "Initialization vector used for encryption and decryption."
                              },
                              "content_auth_tag": {
                                "type": "string",
                                "description": "Used for encryption / decryption processes."
                              },
                              "decrypted_content": {
                                "type": "string",
                                "description": "Decrypted content used for internal processing."
                              },
                              "url": {
                                "type": "string",
                                "format": "uri",
                                "description": "Source page URL, where user can find more information."
                              },
                              "url_iv": {
                                "type": "string",
                                "description": "Initialization vector used for encryption and decryption."
                              },
                              "url_auth_tag": {
                                "type": "string",
                                "description": "Used for encryption / decryption processes."
                              },
                              "supplemental_content": {
                                "type": "string"
                              },
                              "space_id": {
                                "type": "string"
                              },
                              "organization_id": {
                                "type": "string"
                              },
                              "version": {
                                "type": "number",
                                "default": 0,
                                "description": "Version of this source. Increments one each upsert."
                              },
                              "metadata": {
                                "type": "object",
                                "additionalProperties": {
                                  "anyOf": [
                                    {
                                      "type": "string",
                                      "maxLength": 128
                                    },
                                    {
                                      "type": "number"
                                    },
                                    {
                                      "type": "boolean"
                                    }
                                  ]
                                }
                              },
                              "last_updated": {
                                "type": "string"
                              },
                              "created_at": {
                                "type": "string"
                              },
                              "related_components": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "origin": {
                                "type": "string",
                                "maxLength": 16,
                                "description": "A string representing where this exchange originates from."
                              },
                              "object": {
                                "type": "string",
                                "enum": [
                                  "source"
                                ]
                              }
                            },
                            "required": [
                              "id",
                              "key",
                              "title",
                              "content",
                              "content_iv",
                              "content_auth_tag",
                              "url_iv",
                              "url_auth_tag",
                              "space_id",
                              "organization_id",
                              "last_updated",
                              "created_at",
                              "origin",
                              "object"
                            ],
                            "description": "An object representing a document used for training."
                          }
                        }
                      },
                      "required": [
                        "source"
                      ]
                    }
                  },
                  "required": [
                    "status",
                    "returns"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Passed parameters are invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "number"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "status",
                    "message"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized. API key is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "number"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "status",
                    "message"
                  ]
                }
              }
            }
          },
          "402": {
            "description": "No credits remaining.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "number"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "status",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Resource not found.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "number"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "status",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "_id": {
    "buffer": {
      "0": 102,
      "1": 66,
      "2": 111,
      "3": 18,
      "4": 218,
      "5": 98,
      "6": 116,
      "7": 0,
      "8": 18,
      "9": 82,
      "10": 77,
      "11": 93
    }
  }
}
```