Metadata-Version: 2.1
Name: cythereal-magic
Version: 0.0.0
Summary: MAGIC™ API
Home-page: 
Author-email: support@cythereal.com
Keywords: Swagger,MAGIC™ API
Description-Content-Type: Markdown

    --- # The API for accessing Cythereal MAGIC products and services.  ---  ## Authentication  **(Head to our [/auth](../auth/swagger) api to register, login, or generate a token)**  Supported Authentication Schemes:   * HTTP Basic Authentication  * API-KEY in the &#x60;X-API-KEY&#x60; request header  * JWT token in the &#x60;Authorization:\&quot;Bearer {token}\&quot;&#x60; request header  ---  ## Content Negotiation    There are two ways to specify the content type of the response. In order of precedence:     * The **Accept** request header can be set with the desired mime type. The most specific version will prevail. i.e. *application/json* &gt; *application/\**.       *Accept:\&quot;application/json\&quot;*     * The **format** query parameter. (MUST be in lower case)       *?format&#x3D;json*    Supported Formats:     | query parameter | Accept Header            |         |    |-----------------|--------------------------|---------|    | **json**        | application/json         | Default |    | **xml**         | application/xml          |         |    | **csv**         | text/csv                 |         |    | **txt**         | text/plain               |         |    | **explain**     | application/explain+json | Custom type that returns a description of usage of the endpoint |  --- ## Requests  Supported HTTP Methods:   * **GET**  * **POST**  * **PATCH**  * **DELETE**  * **HEAD**  * **OPTIONS**  Every request supports the following query parameters:   * **explain** - (bool) - Returns a detailed explanation of what the endpoint does, as well as potential query parameters that can be used to customize the results    * **download** - (bool) - If set to a truthy value, acts as setting the &#39;Content-Disposition&#39; header to *\&quot;attachment;\&quot;* and will download the response as a file.   * **filename** - (str) - The filename to use for a downloaded file. Ignored if no file is being downloaded.        * **format** - (str) - Used in a similar manner to the *Accept* Header. Use this to specify which format you want the response returned in. Defaults to *application/json*. Current acceptable values are:      * **json** - (application/json)     * **xml** - (application/xml)     * **csv** - (text/csv)     * **txt** - (text/plain)     * **explain** - (application/explain+json)         * Custom type that returns a description of usage of the endpoint   * **no_links** - (bool) - If set to a truthy value, links will be disabled from the response   * **uri** - (bool) - If set to a truthy value, id lists will be returned as uris instead of id strings.  ---  ## GET Conventions ### Possible query parameters:   **(Check each endpoint description, or use *explain*, for a list of available values for each parameter)**    * **read_mask** - A list of values (keys) to return for the resource or each resource within the list     * Comma separated string of variables     * Leaving this field blank will return the default values.     * Setting this value equal to **&#x60;*&#x60;** will include **ALL** possible keys.     * Traversal is allowed with the **&#x60;.&#x60;** operator.     * There are three special keys that can be used with all endponts         * **&#x60;*&#x60;** - This will return all possible values available         * **&#x60;_self&#x60;** - This will include the resources uri         * **&#x60;_default&#x60;** - This will include all default values (Those given with an empty read_mask)           * This would typically be used in conjunction with other &#39;non-default&#39; fields       * Ex:         * &#x60;_default,family,category,_self&#x60;    * **dynamic_mask** - A list of dynamically generated values to return about the resource or each resource within the list     * Comma separated string of variables     * Operates the same as read_mask, but each variable will incur a much greater time cost.     * *May* cause timeouts     * Leaving this field blank or empty will return no dynamic variables.    * **expand_mask** - A list of relational variables to *expand* upon and return more than just the ids     * Comma separated string of variables     * Leaving this field blank will cause all relational data to be returned as a list of ids     * Ex:         * The &#x60;children&#x60; field for a file may return a list of ids normally, but with &#x60;children&#x60; set in the           &#x60;expand_mask&#x60;, it can return a list of child File objects with greater details.  ---  ## POST Conventions  This will create a new resource.  The resource data shall be provided in the request body.  The response will be either a 200 or 201, along with a uri to the newly created resource in the &#x60;Location&#x60; header.  In the case of a long running job, or reprocess, the response will be a 202 along with a **job_id** and it&#39;s corresponding **job_uri** that can be used in the */jobs/* endpoint to see the updated status  ---  ## PATCH Conventions   * The update data shall be provided in the request body.  ### Possible query parameters:   **(Check each endpoint description, or use *explain*, for a list of available values for each parameter)**    * **update_mask** - A list of values to update with this request.     * Comma separated string of variables     * This is required to be set for any and all **PATCH** requests to be processed.     * ONLY the specified variables in the update_mask will be updated regardless of the data in the request body.     * An empty or missing *update_mask* **WILL** result in a 400 Bad Request response  ---  ## DELETE Conventions  A successful response will return 204 No Content  ### Possible query parameters:   * **force** - Forces the deletion to go through     * This is required to be set as a truthy value for any and all **DELETE** requests to be processed.     * Not specifying this on a DELETE request (without *explain* set) **WILL** return a 400 Bad Request response   ---  ## *bulk* endpoints  **Bulk** endpoints are the ones that follow the  &#39;*/&lt;resource\&gt;/bulk/*&#39; convention. They operate in the same fashion as the single resource endpoints (&#39;*/&lt;resource\&gt;/&lt;resource_id\&gt;/*&#39;) except they can process multiple resources on a single call.  They **MUST** be a **POST** request along with the accompanying request body parameter to work:    * **ids** - A list of ids to operate on (For **GET**, **PATCH**, and **DELETE** bulk requests)   * **resources** - A list of resources to operate on (For **POST** bulk requests)  ### Possible query parameters:   **(Check each endpoint description, or use *explain*, for a list of available actions)**    * **action** - This is a string and can only be one of four values:      * **GET** - Returns a list of the resources, in the same order as provided in the request body.      * **POST** - Acts the same as a post on the pluralized resource endpoint.         * Instead of an **ids** request body parameter being provided in the request body, a **resources** list of new resources must be provided.      * **PATCH** - Acts the same as a patch on a single resource.          * Follows the same **PATCH** conventions from above*      * **DELETE** - Acts the same as a delete on a single resource.          * Follows the same **DELETE** conventions from above*    * **strict** - Causes the bulk endpoint to fail if a single provided id fails     * Boolean     * If set to True, the bulk call will ONLY operate if it is successful on ALL requested resources.     * If even a single resource is non-existent/forbidden, the call will fail and no side effects will take place.  ---  ## Pagination:  Pagination can be done in combination with sorting and filtering on most endpoints that deal with lists (including **PATCH** and **DELETE** calls)  ### Pagination query paramters:        * **page_size** - The number of results to return (default: 50)   * **page_count** - The page used in pagination (default: 1)   * **skip_count** - A specified number of values to skip before collecting values (default: 0)  ---  ## Sorting:  Sorting can be done in combination with filtering and pagination on most endpoints that deal with lists (including **PATCH** and **DELETE** calls)  ### Sorting query parameter:   **(Check each endpoint description, or use *explain*, for a list of available sorters)**    * **order_by** - A list of variables to sort the query on     * Comma separated string of variables     * Regex Pattern - &#x60;^(-?[\w]+,?)*$&#x60;     * Variables are sorted in ascending order by default     * Prepend the variable with a &#x60;-&#x60; to change it to descending order     * Multiple sorters can be specified, with precedence matching the order of the parameter     * Ex:         * &#x60;-object_class,create_time&#x60;  ---  ## Filtering:  Filtering can be done in combination with pagination and sorting on most endpoints that deal with lists (including **PATCH** and **DELETE** calls)  ### Filters query parameter:   **(Check each endpoint description, or use *explain*, for a list of available filters)**    * **filters** - A string of filters used to narrow down the query results.     * Semi-colon separated string of variables     * Regex patterns:         * Single filter:             * &#x60;^\ *(NOT\ +)?[\w]+__[a-z]+\(.+\)\ *&#x60;              * &#x60;NOT variable__comparator(value)&#x60;          * Multiple Filters:             * &#x60;^{SINGLE_FILTER_REGEX}(\ +(AND|OR|;)\ +{SINGLE_FILTER_REGEX})*$&#x60;              * &#x60;NOT variable__comparator(value) AND NOT variable__comparator(value); variable__comparator(value)&#x60;      * Logical operator order of precedence:         * **AND**         * **OR**         * **;** **(Semi-colon separation denotes conjunction)**         * Example order of precedence:             * **exp1;exp2 AND exp3 OR exp4** is equivalent to **(exp1) AND ((exp2 AND exp3) OR (exp4))**      * Available Comparators:         * **eq** - Equal         * **ne** - Not Equal         * **lt** - Less than         * **lte** - Less than or equal         * **gt** - Greater than         * **gte** - Greater than or equal         * **in** - In (for list values)         * **nin** - Not In (for list values)         * **regex** - Regular Expression Match         * **iregex** - Case Insensitive Regular Expression Match      * The format for **in** and **nin** which operate on arrays is:         * **[]** - The list of values must be enclosed within brackets.         * **,** - The value separtion token is a comma.         * **&lt;variable\&gt;__&lt;comp\&gt;([&lt;value1\&gt;,&lt;value2\&gt;])**      * Examples:         * &#x60;create_time__gte(2022-01-01T13:11:02);object_class__regex(binary.*)&#x60;          * &#x60;create_time__gte(2022-01-01) AND create_time__lt(2022-02-01) AND NOT match_count__gt(10)&#x60;          * &#x60;create_time__gte(2022-01-01) AND create_time__lt(2022-02-01)&#x60;  ---  ## Responses  All responses **WILL** be of type &#x60;APIResponse&#x60; and contain the following fields:  * &#x60;success&#x60; | Boolean value indicating if the operation succeeded.  * &#x60;status&#x60; | Status code. Corresponds to the HTTP status code.   * &#x60;message&#x60; | A human readable message providing more details about the operation.  * &#x60;links&#x60; | A dictionary of &#x60;name&#x60;: &#x60;uri&#x60; links providing navigation and state-based actions on resources  * &#x60;errors&#x60; | Array of error objects. An error object contains the following properties:      * &#x60;reason&#x60; | Unique identifier for this error. Ex: \&quot;FileNotFoundError\&quot;.      * &#x60;message&#x60;| Human readable error message.      * &#x60;parameter&#x60;| The parameter (if any) that caused the issue.  Successful operations **MUST** return a &#x60;SuccessResponse&#x60;, which extends &#x60;APIResponse&#x60; by adding:  * &#x60;success&#x60; | **MUST** equal True  * &#x60;resource&#x60; | Properties containing the response object.     * (In the case of a single entity being returned)  **OR**  * &#x60;resources&#x60; | A list of response objects.     * (In the case of a list of entities being returned)  Failed Operations **MUST** return an &#x60;ErrorResponse&#x60;, which extends &#x60;APIResponse&#x60; by adding:  * &#x60;success&#x60; | **MUST** equal False.  Common Failed Operations that you may hit on any of the endpoint operations:  * 400 - Bad Request - The request is malformed  * 401 - Unauthorized - All endpoints require authorization  * 403 - Forbidden - The endpoint (with the given parameters) is not available to you  * 404 - Not Found - The endpoint doesn&#39;t exist, or the resource being searched for doesn&#39;t exist  ---  ## Example Inputs  Here are some example inputs that can be used for testing the service:  * &#x60;binary_id&#x60;: **ff9790d7902fea4c910b182f6e0b00221a40d616**  * &#x60;proc_rva&#x60;: **0x1000**  * &#x60;search_query&#x60;: **ransomware**  ---   # noqa: E501
    
