Ragic HTTP API (3.0)

The Ragic HTTP API is a REST-style interface that lets you read, create, update, and delete records on any Ragic form. You can use any HTTP client — cURL, Postman, or your programming language's HTTP library.

The Ragic REST API allows you to query any data that you have on Ragic, or to execute create / update / delete operations programmatically to integrate with your own applications. Since the API is based on REST principles, it's very easy to write and test applications. You can use your browser to access URLs, and you can use pretty much any HTTP client in any programming language to interact with the API. HTTP requests can be issued with two content types, form data and JSON. However, for file uploads, form data is the only option.

You can test most GET method APIs easily by entering API endpoint URLs in your browser. For example, you can try the following URL to access customer account information on the Ragic demo:

https://www.ragic.com/demo/sales/1?api

Note that you may need to modify www to na3 , ap5 , or eu2 in your URL based on your Ragic account URL. But it's not as easy to create POST method requests on your browser, so we recommend a tool called cURL for you to create all types of HTTP requests you want to test our API. Our document will also be using cURL commands as samples API calls, but you can also use any tool that you're familiar with to create HTTP requests and parse responses. You can download cURL for your platform at https://curl.haxx.se/download.html , and you can also read its full documentation at https://curl.haxx.se/docs/manpage.html . But don't worry, we'll tell you about the necessary usages of cURL as we explain the Ragic HTTP API. After you have downloaded cURL, you can use the following command to access the same endpoint we described above, and you should see the same output as you would in a browser.

curl https://www.ragic.com/demo/sales/1?api

Please note that when using CURL, -d does not encode the content as URL string. If your string content has characters like % or & please use the option --data-urlencode instead of -d.

Postman is a tool that helps to send HTTP requests without having to code. You can see Postman’s documentation here, and Postman can be downloaded here. Postman is recommended for users with little technical experience, and the fundamentals will be introduced in this tutorial. The user interface for Postman looks like the image below:

1. The dropdown menu that lists all HTTP methods to select from
2. The destination URL that the HTTP request is sent to
3. The action button that sends out the HTTP request
4. Attributes associated with the HTTP request

For the image above, the HTTP request is a GET request, and it is being sent to https://www.ragic.com/demo/sales/1 with a query parameter "api" that has no value attached to it. The image below shows the list of HTTP methods from the dropdown menu.

In a lot of cases you need to find a Field ID for a field. The field id is an unique number that Ragic assigns to each field that you created. It gives your program an unambiguous way to refer to a field. With this design, fields can even have the same name under a sheet and Ragic will still be able to distinguish between them. Right-click on any sheet name and select Javascript Workflow to view the Field IDs associated with each field in the sheet. Alternatively, you can go to the design mode, and click on the field you want to reference to. On the left sidebar, you're going to see the Field Name. The Field ID is right under the Field Name. For other ways to find Field IDs , please refer to this article.

You can find the API endpoint for your Ragic form or entry by passing api as a query string parameter to specify this is an API request.

https://www.ragic.com/{ACCOUNT_NAME}>/{TAB_FOLDER}>/{SHEET_INDEX}/{RECORD_ID}?v=3&api

Please Note:

• It is required to modify www to na3 , ap5 , or eu2 in the API URL based on your Ragic database account URL.
• The API version is specified by the URL parameter, For details, see Specifying the API Version.

It's a good practice to specify the API version every time you send your request to ensure a correct version. If the version is not specified, the latest version will be used, but unexpected changes to the API may cause problems in your application. For example if you usually access your Ragic form using the following URL:

https://www.ragic.com/demo/sales/1

Its HTTP API endpoint URL would be:

https://www.ragic.com/demo/sales/1?v=3&api

Or for a single entry in your form, you would include an id (for example record id of 1) to specify an entry:

https://www.ragic.com/demo/sales/1/1

Its corresponding HTTP API endpoint URL is simply:

https://www.ragic.com/demo/sales/1/1?v=3&api

We don't have a limit on our API calls as long as it's under reasonable use. If you're not sure about your use, feel free to just drop us a message at support@ragic.com to check with us. While there is no limit on API usage, there is a queue mechanism for each database account. The maximum size of the queue is 50, and it stops accepting API requests when it is full. Therefore, we encourage waiting for the response of one request before sending another. Note that this limit currently only applies to GET API requests. This is only to ensure reasonable use of our system, so that there will not be disproportionately heavy use in smaller accounts. A manual review process will be triggered, if the usage exceeds 5 requests per second, to determine whether throttling will be applied.

Currently, the API uses a date-based parameter for versioning while remaining compatible with the legacy numeric versions. The API supports the following two versioning mechanisms:

• Current version (recommended): version=YYYY-MM-DD
• Legacy version (still supported): v=1, v=2, v=3

The recommended format is a date string, for example: version=2025-01-01. All future API versions will only support the date-based format.

Legacy versions use numeric parameters, for example: v=1 , v=2 , v=3. Legacy versions remain supported but are not recommended for new integrations.

If no version parameter is specified in the request, the API will default to the latest version.

You authenticate to the Ragic API by providing one of your API keys in the request. Your API keys carry many privileges, so be sure to keep them secret! Because when your code accesses Ragic via an API key, it will basically log in as the user of the API key and execute read write as this user. We highly recommend creating a separate user for API key access. This way the API access will not be mixed with a organizational user, which will make the system audit trail much clearer and debugging of your API program much easier. Authentication to the API occurs via HTTP Basic Auth. Provide your API key as the basic auth username. You do not need to provide a password. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

curl https://www.ragic.com/demo/sales/1\
   --get -d api \
   -H "Authorization:Basic YOUR_API_KEY_GOES_HERE"

Note that the HTTP header name is Authorization, and the value is your API key preceded with "Basic ", Basic with a space at the end, and you may need to modify www to na3 , ap5 , or eu2 in your URL based on your Ragic account URL. You can generate your API key in Personal Settings. Most HTTP clients (including web-browsers) present a dialog or prompt for you to provide a username and password (empty) for HTTP basic auth. Most clients will also allow you to provide credentials in the URL itself. If for some reason that you are not able to send the API key as HTTP header or basic authorization, you can send the API key as a parameter with the name APIKey. You will need to add this parameter for every single request you send.

curl https://www.ragic.com/demo/sales/1\
   --get -d api \
   -d "APIKey=YOUR_API_KEY_GOES_HERE"

Sometimes if your platform does not support HTTP Basic authentication, you can pass the user's e-mail and password as log in credentials to authenticate your program. If you registered through Sign in with Google, make sure to register a Ragic password before proceeding with this tutorial. Please only use this when you can not authenticate with HTTP Basic Authentication. You send a request for a session id with a valid e-mail and password. You can issue a HTTP request using the -d argument containing the id and password. The -c parameter will store sessionId in the cookie jar file specified:

curl --get -d "u=jeff@ragic.com" \
 --data-urlencode "p=123456" \
 -d "login_type=sessionId" \
-d api \
 -c cookie.txt \
 -k \
 https://www.ragic.com/AUTH

If authentication failed, server will return -1. If authenticated, you will receive a session id in the response like this:

2z5u940y2tnkes4zm49t2d4

Note that this authentication method is session based, and session is server dependent. You may need to modify the url based on the location of the account you wish to access. For example, https://ap8.ragic.com/AUTH for accounts that reside on server https://ap8.ragic.com. **To use the returned sessionId in future requests to remain authenticated, please include the sessionId in url parameter as sid= For example, https://www.ragic.com/demo/sales/1?sid= The use of Ragic API will be covered in later chapters, just remember to include your session ID in this manner to remain authenticated. ** If you would like to retrieve detailed info on the log in user, you can also provide an additional json=1 parameter so that Ragic will return a json object containing the details of the user.

curl --get -d "u=jeff@ragic.com" \
 --data-urlencode "p=123456" \
 -d "login_type=sessionId" \
 -d "json=1" \
-d api \
 -c cookie.txt \
 -k \
 https://www.ragic.com/AUTH

The returned format will look something like this:

{
"sid":"8xkz874fdftl116vkd3wgjq0t",
"email":"jeff@ragic.com",
"accounts":
  {
    "account":"demo",
    "ragicId":25,
    "external":false,
    "groups":["EVERYONE","SYSADMIN"]
  }
}

For example, this is the API response for https://www.ragic.com/demo/sales/1?v=3 &api. Remember to specify your cookie jar file in the call like "-b cookie.txt"

{
"1":{
  "_ragicId": 1,
  "_star": false,
  "Account Name": "Alphabet Inc.",
  "_index_title_": "Alphabet Inc.",
  "Short Name": "",
  "Account ID": "C-00002",
  "EIN / VAT Number": "",
...
...
},
"0":{
  "_ragicId": 0,
  "_star": false,
  "Account Name": "Ragic, Inc.",
  "_index_title_": "Ragic, Inc.",
  "Short Name": "Ragic",
  "Account ID": "C-00001",
  "EIN / VAT Number": "",
...
...

The listing is defaulted to 1000 entries. You can add paging parameter limit according to the following sections to get more entries. The data in the subtables are displayed as the sample below. The attribute name is subtable followed by the subtable ID to identify which subtable it is. The content of the subtable is presented the same way as the fields in a form.

"_subtable_2000154": {
    "0": {
      "_ragicId": 0,
      "Contact Name": "Jeff Kuo",
      "Title": "Technical Manager",
      "Phone": "886-668-037",
    },
    "1": {
      "Contact Name": "Amy Tsai",
      "Title": "Marketing",
      "Phone": "",
    },

If your application does not need the data in the subtables, you can add the parameter subtables=0 to turn off the fetching of subtable data. The comments of the entries is retrieved as subtables also. It will be retrieved in a subtable with the field id of 61, but you will need to add parameter comment=true when retrieving data for comment data to be returned.

Very often your database contains a large amount of entries, so it's better to apply filters when you retrieve data. Ragic API filters are in a special format You can use the parameter "where" to add a filter condition to a query as below:

curl --get -d "where=2000123,eq,Alphabet Inc." \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
-d api \
https://www.ragic.com/demo/sales/1

The parameter is a "," comma delimited format, with at least 3 arguments.

1. Field id of the field that you would like to filter.
2. Operand in the form of integer to specify your filter operation. The list of operands are listed below.
3. The value that you would like to filter the field with. Remember if your value might include a "," comma character, please URL encode it or just use a %2C instead to avoid collision.

You can supply a query with multiple filter conditions as below:

curl --get -d "where=2000123,eq,Alphabet Inc." \
-d "where=2000127,eq,Jeff Kuo" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
-d api \
https://www.ragic.com/demo/sales/1

Here's the list of operands that you can use:

Please note that:

1. When you filter by date or date time, they will need to be in the following format: yyyy/MM/dd or yyyy/MM/dd HH:mm:ss.
2. You don't need to fill the third argument if you want to filter empty values, for example, "where=2000127,eq,".
3. When multiple "eq", "regex", or "like" conditions are applied to the same field, the filter will be treated as an OR condition. For example, to retrieve records where field id 1000001 is either Ratshotel OR Claflin, **"where=1000001,eq,Ratshotel &where=1000001,eq,Claflin" **.
4. When both gte/gt and lte/lt conditions are applied to the same field, the filter will be treated as an AND condition (applicable to Number Fields or Date Fields for specifying a range). For example, to retrieve records where field id 105 falls between 2025/10/01 AND 2025/10/31, **"where=105,gte,2025/10/01 &where=105,lte,2025/10/31" **.
5. If the filter value contains % followed by two hexadecimal characters (e.g., ABC%DEF), it must be URL-encoded twice. This is because, in addition to URL-encoding the query string once during transmission, filter values must be URL-encoded a second time to prevent special characters from affecting server-side parsing. For example, to retrieve records where field ID 1000002 has the value ABC%DEF, the filter value must be URL-encoded twice, resulting in where=1000002,eq,ABC%2525DEF.

There are some system fields that has special field ids that you can use in your query. Common system fields listed below:

You can also use a full text search as a query filter. Just provide your query term in the parameter fts and the matched result will be returned.

curl --get -d "fts=Alphabet" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
-d api \
https://www.ragic.com/demo/sales/1

You can also apply Shared View. Just set the id as below.

curl --get -d "filterId=YOUR_SHARED_VIEW_ID" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
-d api \
https://www.ragic.com/demo/sales/1

You could get the id by clicking the Shared View URL.

Very often you do not want to fetch all entries with one request, you can use the limit and offset parameters to specify how many entries that you would like to retrieve, and how many entries that you would like to skip at the start, so clients can implement pages for viewing entries. The usage of limit and offset parameters is similiar to SQL limit parameter. Offset is how many entries that you would like to skip in the beginning, and limit is how many entries that you would like to be returned. Returned data is defaulted to 1000 entries , you will need to provide limit parameters if you want your response to have more than 1000 entries. The format is as follows:

limit=<limit>&offset=<offset>
</offset></limit>

The offset parameter is the number of entries that should be skipped before returning, used for going through pages that has been retrieved. The limit parameter is the max number of records that should be returned per call. For example the below call will skip the first 5 entries, and return 6 ~ 13, a total of 8 entries.

curl --get -d "limit=8" \
-d "offset=5" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
-d api \
https://www.ragic.com/demo/sales/1

Without any ordering, the data is by default ordered by creation date and time, from oldest to latest. If you would like to have the latest result first, you can specify reverse=true like this:

curl --get -d "reverse=true" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
-d api \
https://www.ragic.com/demo/sales/1

You can also specify how the entries are ordered by adding the order parameter. It's also kind of similar to the ORDER BY clause in SQL, its value is a comma separated string with two arguments. The first one is the field id of the domain that you would like the entries to be sorted according to, and the second one is the order: either ASC for ascending order, or DESC for descending order.

curl --get -d "order=800236,DESC" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
-d api \
https://www.ragic.com/demo/sales/1

Adding a callback function parameter will enclose the returned JSON object as a argument in a call to the callback function specified by you. This is especially useful when you're accessing our API using Javascript, you may need this to do cross domain ajax calls. For example, adding callback=testFunc as below:

curl --get -d "callback=testFunc" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
-d api \
https://www.ragic.com/demo/sales/1

Will enclose the returned JSON object in a function call so you can process the returned data in your callback function:

testFunc({"17": {

"Account Name": "Dunder Mifflin",

"Account Owner": "Jim Halpert",

"Phone": "1-267-922-5599",

 ...

 ...

});

The JSON data format uses the field name string as the attribute name, you can use a "naming" parameter to specify that you would like to use field id as the attribute name to identify a field. Possible values include: EID (Field Id), FNAME (Field Name).

curl --get -d "naming=EID" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
-d api \
https://www.ragic.com/demo/sales/1

There are several other useful parameters that you can apply to your HTTP GET request to change the content of the response:

CODEBLOCK_0_PLACEHOLDER | | ignoreMask | When ignoreMask=true is given, the field value of "Masked text" will be unmasked if you are in the viewable groups. Click here for more information about "Masked text" field. | | ignoreFixedFilter | When ignoreFixedFilter=true is given, the fixed filter on this sheet will be ignored. But note that this will only work when the API call API key user has the SYSAdmin privilege. |

On the JSON returned by your HTTP API call, you will see something like this for file upload field or image upload fields:

"1000537": "Ni92W2luv@My_Picture.jpg",

You will be able to download the file using a separate call like this (assuming your account name is "demo" and API call url being https://www.ragic.com/demo/sales/1?v=3&api) :

https://www.ragic.com/sims/file.jsp?a=demo&f=Ni92W2luv@My_Picture.jpg

The format is:

https://www.ragic.com/sims/file.jsp?a=< account name >&f=< file name >

Remember to encode your file name when you send it as an URL. Your actual file name will start after the @ character, this is to avoid file name collision.

For example, if you have an URL to the record as follows

https://www.ragic.com/demo/sales/1/41

1. Printer Friendly

You can retrieve an HTML printer friendly version like this, by adding a .xhtml to the end:

https://www.ragic.com/demo/sales/1/41.xhtml

2. PDF or Excel Version

You can add a .pdf for a PDF version, .xlsx for an Excel version:

https://www.ragic.com/demo/sales/1/41.pdf
https://www.ragic.com/demo/sales/1/41.xlsx

3. Mail Merge

You can retrieve a Mail Merge of a record, by adding .custom? and a Mail Merge CID to specify which template (which is 1 for the mail merge template used in this case):

https://www.ragic.com/demo/sales/1/41.custom?cid=1

To obtain the cid of a mail merge, you can manually download a mail merge from the Ragic user interface first, and pay attention to the cid parameter in the download url.

https://www.ragic.com/demo/sales/1/41.custom?rn=41&<b>cid=1</b>

4. Custom Print Report

You can retrieve a Custom Print Report of a record by appending .carbone? to the URL, along with the following parameters (joined with &).

https://www.ragic.com/demo/sales/1/41.carbone?fileFormat=pdf&ragicCustomPrintTemplateId=1&fileNameRefDomainId=1001000

(1) File format syntax: fileFormat="file format" (e.g., pdf, png, docx). Example: fileFormat=pdf (2) Custom template ID syntax: ragicCustomPrintTemplateId="Template ID". Example: ragicCustomPrintTemplateId=1 To obtain the "Template ID", first manually download the Custom Print Report and find the Template ID parameter in the download URL:

https://www.ragic.com/demo/sales/1/41.carbone?fileFormat=pdf&fileNameRefDomainId=-1&<b>ragicCustomPrintTemplateId=2</b>

(3) File name referenced field syntax (Optional)：fileNameRefDomainId="Field ID". Example: fileNameRefDomainId=1001000

If you are not using simple HTML forms to create entries on Ragic, you will need to create API requests to create the entries. The endpoints for writing to a form is the same as reading them, but you issue a POST request instead of a GET request. The API now supports JSON data, and it is the recommended way to make HTTP requests. To POST JSON data, you need to change Body settings to raw JSON, as the image below. What you need to do is use the field ids of the fields as name, and the values that you want to insert as parameter values. Please note that your user will need write access to the form for this to work.

curl -F "2000123=Dunder Mifflin" \
 -F "2000125=1-267-922-5599" \
 -F "2000127=Jeff Kuo" \
-F "api=" \
 -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
 https://www.ragic.com/demo/sales/1

The equivalent JSON format is as below,

{
    "2000123": "Dunder Mifflin",
    "2000125": "1-267-922-5599",
    "2000127": "Jeff Kuo",
}

If the field is a multiple selection that can contain multiple values, you can have multiple parameters with the same field id as names. If the field is a date field the value will need to be in the format of yyyy/MM/dd or yyyy/MM/dd HH:mm:ss if there's a time part. So a request would look like this:

curl -F "2000123=Dunder Mifflin" \
 -F "2000125=1-267-922-5599" \
 -F "2000127=Jeff Kuo" \
 -F "1000001=Customer" \
 -F "1000001=Reseller" \
 -F "2000133=2018/12/25 23:30:00" \
 -F "api=" \
 -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
 https://www.ragic.com/demo/sales/1

The equivalent JSON format is as below, the squre brackets for the field ID 1000001 allows for multiple values in one statement.

{
    "2000123": "Dunder Mifflin",
    "2000125": "1-267-922-5599",
    "2000127": "Jim Halpert",
    "1000001": ["Customer", "Reseller"],
    "2000133": "2018/12/25 23:30:00"
}

If you would like to insert data into the subtables at the same time, you will need a slightly different format for the fields in the subtables because Ragic needs a way to determine if the field values belong to the same entry in a subtable. If the field values are in the same subtable row, assign them with the same negative row id with each other. It can be any negative integer. It's only a way to determine that they are in the same row.

2000147_-1=Bill
2000148_-1=Manager
2000149_-1=billg@microsoft.com

2000147_-2=Satya
2000148_-2=VP
2000149_-2=satyan@microsoft.com

The whole request would look like this:

curl -F "2000123=Dunder Mifflin" \
 -F "2000125=1-267-922-5599" \
 -F "2000127=Jeff Kuo" \
 -F "1000001=Customer" \
 -F "1000001=Reseller" \
 -F "2000133=2018/12/25 23:30:00" \
 -F "2000147_-1=Bill" \
 -F "2000148_-1=Manager" \
 -F "2000149_-1=billg@microsoft.com" \
 -F "2000147_-2=Satya" \
 -F "2000148_-2=VP" \
 -F "2000149_-2=satyan@microsoft.com" \
-F 'api=' \
 -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
 https://www.ragic.com/demo/sales/1

The equivalent JSON format is as below,

{

    "2000123": "Dunder Mifflin",
    "2000125": "1-267-922-5599",
    "2000127": "Jim Halpert",
    "1000001": ["Customer", "Reseller"],
    "2000133": "2018/12/25 23:30:00"
    "_subtable_2000154": {
        "-1": {
            "2000147": "Bill",
            "2000148": "Manager",
            "2000149": "billg@microsoft.com"
        },
       "-2": {
            "2000147": "Satya",
            "2000148": "VP",
            "2000149": "satyan@microsoft.com"
        }
    }
}

If you would like to populate a file upload field , just make sure that the request encoding type is a multipart/form-data. The HTML equivalent would be setting enctype='multipart/form-data' With a multipart request, you can put the file in your request, and just put the file name as the field value.

1000088=test.jpg

Ragic supports using POST, PUT, and PATCH method to modify an entry. The endpoint for modifying an entry is the same as reading an existing entry. Notice that when you create an entry, the endpoint points to a Ragic sheet, but when you edit an entry, your endpoint will need an extra record id to point to the exact record.

https://www.ragic.com/<account>/<tab folder>/<sheet index><b>/<record id></record></b>?api

</sheet></tab></account>

All you need to provide is the field ids of the fields that you would like to modify to. If the field is a date field the value will need to be in the format of yyyy/MM/dd or yyyy/MM/dd HH:mm:ss if there's a time part.

curl -F "2000123=Dunder Mifflin" \
 -F "2000127=Jim Halpert" \
 -F "api=" \
 -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
 https://www.ragic.com/demo/sales/1<b>/3</b>

The equivalent JSON format is as below,

{
    "2000123": "Dunder Mifflin",
    "2000127": "Jim Halpert"
}

For subtables, it's a bit more tricky. Because Ragic will need to know which row that you're editing. So you will need to find the row id of the row that you're editing. This information can be found from an API call. As we mentioned in earlier chapter, the returned format for an entry with subtables look like this:

"_subtable_2000154": {
    "0": {
      "Contact Name": "Jeff Kuo",
      "Title": "Technical Manager",
      "Phone": "886-668-037",
      "E-mail": "jeff@ragic.com",
...
...
    },
    "1": {
      "Contact Name": "Amy Tsai",
      "Title": "Marketing",
      "Phone": "",
...
...
    },
    "2": {
      "Contact Name": "Allie Lin",
      "Title": "Purchasing",
...
...

In the subtable, 1 is the row id for the contact Amy Tsai, and 2 is the row id for the contact Allie Lin. With this row id, you can modify data in the subtable pretty much like how you create an entry with subtable data. You use the row id as the identifier following the field id. You only need to put in the fields that you want to modify:

2000147_1=Ms. Amy Tsai
2000148_1=Senior Specialist

2000148_2=Senior Manager

The whole request would be like this:

curl -F "2000123=Dunder Mifflin" \
 -F "2000127=Jim Halpert" \
 -F "2000147_1=Ms. Amy Tsai" \
 -F "2000148_1=Senior Specialist" \
 -F "2000148_2=Senior Manager" \
 -F "api=" \
 -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
 https://www.ragic.com/demo/sales/1<b>/3</b>

The equivalent JSON format is as below,

{
    "2000123": "Dwight Schrute",
    "2000127": "Jim Halpert" ,
    "_subtable_2000154": {
        "29" :{
            "2000147": "Ms. Amy Tsai",
            "2000148": "Senior Specialist"
        },
        "30" :{
            "2000148": "Senior Manager"
        }
    }
}

If you want to delete a subtable row, you can create a request like:

DELSUB_<subtable key>=<subtable row id>
</subtable></subtable>

The equivalent JSON format is as below,

_DELSUB_<subtable key>=[<subtable row id>,<subtable row id>,...,<subtable row id>];
</subtable></subtable></subtable></subtable>

For example, if you want to delete the contact Arden Jacobs, the whole request would be like this:

curl -F "DELSUB_2000154=3" \
 -F "api=" \
 -H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
 https://www.ragic.com/demo/sales/1<b>/3</b>

The equivalent JSON format is as below,

{
    "_DELSUB_2000154": [3]
}

Using the JSON format for subtable row deletion allows you to specify multiple rows in a simple manner,

{
    "_DELSUB_subtable key": [<subtable row id>,..., <subtable row id>]
}
</subtable></subtable>

There are many useful parameters that you can use when creating or updating records on Ragic to save your time writing duplicate code for what can be done on Ragic.

Specifying doLinkLoad=first tells the Ragic API to execute all link and load operations first, and then recalculate all formulas when a record is created or updated.

When using either of the above parameters and formula recalculation is required, you must also specify doFormula=true. | | doWorkflow | Specifying doWorkflow=true tells Ragic API to execute the workflow script associated with this API call. | | notification | Specifying notification=true tells Ragic API to send out notifications to relevant users, or false, otherwise. The default is true when not specified. | | checkLock | Specifying checkLock=true tells Ragic API to check if the record is locked before an update, and not edit the record if the record is locked. |

Deleting an entry is very similar to reading an entry. All you need to do is change the request method from GET to DELETE. When it's a DELETE request, the entry at the API endpoint will be deleted.

curl -X DELETE \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
-d "api"  \
https://www.ragic.com/demo/sales/1/3

Make sure your content-type is multipart/form-data , and you will be able to upload files.

curl -F "1000088=@/your/file/path" \
-F "api=" \
-F "v=3" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
https://www.ragic.com/demo/sales/1

After a success uploading, you will receive your file in this format.

"1000088": "Ni92W2luv@test.jpg",

Hover your mouse over the boxed area to expose the drop-down list, and select the "File" option to allow file uploads. If you want to get files just uploaded, follow instruction here. If you want to upload files via link, download it first and then follow instruction above.

curl -o __TEMP_FILE__ YOUR_IMAGE_LINK
curl -F "1000002=@__TEMP_FILE__" -F "api=" -F "v=3" -H "Authorization:Basic YOUR_API_KEY" https://www.ragic.com/demo/sales/1

Remember to replace YOUR_IMAGE_LINK and YOUR_API_KEY You can find your API key in your Personal Settings page.

Make sure your content-type is multipart/form-data.

curl -F "at=@/your/file/path" \
-F "c=yourComment"
-F "api=" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
https://www.ragic.com/demo/ragicsales-order-management/10001/2

In the request body, the value of the parameter c is the comment(required), and the value of the parameter at is the attachment(optional). You can find your API key in your Personal Settings page.

Response:

{
  "61": "2025/02/13 14:30",
  "65": "John Smith",
  "66": "Please review this order.",
  "67": "",
  "73": "1739425800000"
}

Field 61 is the formatted timestamp, 65 is the commenter's name, 66 is the comment text, 67 is the attachment filename (empty if none), and 73 is the raw timestamp in milliseconds.

You must have SYSAdmin privileges to use this API. Before using this API, please enable the "Periodic Import from URL" feature. Once the setup is complete, you can trigger the import by calling the following API:

curl -F "importData="
-F "api=" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
https://www.ragic.com/demo/ragicsales-order-management/10001

When you need to create or update a large amount of data , you can also use this method to import all at once instead of making multiple API calls. You can find your API key in your Personal Settings page.

Response:

{
  "status": "SUCCESS",
  "msg": "Import completed."
}

To lock or unlock data using the HTTP API, simply append the query strings "api" and "lock"/"unlock" to the target record’s URL and send the request using the POST method.

curl -X POST https://www.ragic.com/demo/ragicforms23/10004/102?api&lock

curl -X POST https://www.ragic.com/demo/ragicforms23/10004/102?api&unlock

The permissions for locking/unlocking are the same as when performing the action through the form interface. You can find your API key in your Personal Settings page.

Response:

{
  "status": "SUCCESS",
  "code": 200
}

To execute an Action Button through the Http API, you first need to obtain the Action Button ID. Use the GET method to send the following request:

curl "https://{serverName}/{accountName}{path}/{sheetIndex}/metadata/actionButton?api&category=massOperation" \
  -H "Authorization: {Basic apiKey}"

After obtaining the Action Button ID , you can use the POST method to send the following request and execute the specified Action Button on the target record:

curl -X POST "https://{serverName}/{accountName}{path}/{sheetIndex}/{recordId}?api&bId={buttonId}" \
  -H "Authorization: Basic apiKey"

Note: In addition to having permission to execute the Action Button, you must also have permission to view the target record in order to use this Http API. You can find your API key in your Personal Settings page.

Response:

{
  "status": "SUCCESS",
  "msg": "Action completed."
}

If the request returned in error, it will look something like this:

{
"status": "ERROR",
"code": 303,
"msg": "Your account has expired."
}

Here is a list of the HTTP status code that might be returned on a Ragic request:

If there was an error processing your request, it will generally contain an error code and a description. Here is the list of error codes that you might receive as a response to a Ragic request:

Mass operation APIs are designed to perform the same set of operations for multiple records on a sheet in one single request. There are two ways of specifying the records to be updated:

• where filters

https://www.ragic.com/< account >/< tab folder >/< sheet index >/massOperation/< Mass Operation Type >?api&where=< Field ID >,< Filter Operand >,< Value >

• recordId in query string, recordId=< recordId >. e.g. recordId=1&recordId=2

https://www.ragic.com/< account >/< tab folder >/< sheet index >/massOperation/< Mass Operation Type >?api&recordId=< recordId >

• Mass operation APIs are aynschronous operations.
  • It is required to modify www to na3, ap5, or eu2 in the API URL based on your Ragic database account URL.

HTTP Method - POST
URL - https://www.ragic.com/< account >/< tab folder >/< sheet index >/massOperation/< Mass Operation Type >?api

Headers
Authorization: Basic < API Key >

Body
{
// JSON data that describes the operation to be performed
}

==========

Response
{
"taskId": < A UUID That Identifies The Task >
}

The mass lock API allows locking or unlocking multiple records at once. Mass Lock Document

HTTP Method - POST
URL - https://www.ragic.com/< account >/< tab folder >/< sheet index >/massOperation/massLock?api

{
"action": < lock or unlock >
}

==========

Response
{
"taskId": "6dbc796a-07d5-475b-b578-d254eb30f7d2"
}

The mass approval API allows approval or rejection of multiple records at once. Mass Approval Document

HTTP Method - POST
URL - https://www.ragic.com/< account >/< tab folder >/< sheet index >/massOperation/massApproval?api

{
"action": < approve or reject >,
"comment": < optional comment > // optional
}

==========

Response
{
"taskId": "6dbc796a-07d5-475b-b578-d254eb30f7d2"
}

The mass action button API allows the execution of an action button on multiple records at once. Mass Action Button Document

HTTP Method - POST
URL - https://www.ragic.com/< account >/< tab folder >/< sheet index >/massOperation/massActionButton?api

{
"buttonId": < button ID >
}

==========

Response
{
"taskId": "6dbc796a-07d5-475b-b578-d254eb30f7d2"
}

To Fetch The List Of Available Action Buttons On A Sheet

HTTP Method - GET
URL - https://www.ragic.com/< account >/< tab folder >/< sheet index >/metadata/actionButton?api&category=massOperation

==========

Response
{
"actionButtons": [
{
"id": < button ID 1 >,
"name": < button name 1 >
},
.....
,{
"id": < button ID 2 >,
"name": < button name 2 >
}
]
}

The mass update API allows updates of field values on multiple records at once. Mass Update Document

HTTP Method - POST
URL - https://www.ragic.com/< account >/< tab folder >/< sheet index >/massOperation/massUpdate?api

{
    "action": [
        {
            "field": < Field ID >,
            "value": < New Field Value >
        }
    ]
}

==========

Response
{
    "taskId": "6dbc796a-07d5-475b-b578-d254eb30f7d2"
}

The mass update API also supports using on Internal Users and External Users, but there are some restrictions.

The following fields cannot be mass updated:

• E-mail (domainId: 1)
• Full Name (domainId: 4)
• System Log (domainId: 10)
• Status (domainId: 31)
• Internal/External (domainId: 43)

Mass updating Ragic Groups (domainId: 3) has to follow the rules below:

• The value of the key "value" has to be written in JSON Array, which has strings as its content.
• All special characters has to be used with escape character(\), especially " has to be used as ".

HTTP Method - POST
URL - https://www.ragic.com/< account >/< tab folder >/< sheet index >/massOperation/massUpdate?api

{
    "action": [
        {
            "field": 3,
            "value": "[\"SYSAdmin\"]"
        }
    ]
}

==========

Response
{
    "taskId": "6dbc796a-07d5-475b-b578-d254eb30f7d2"
}

• In Internal Users, it is necessary to have at least one user who's Ragic Group is SYSAdmin.
  • In External Users, the name of users' Ragic Group has to start with "x-" or "X-".

The mass search and replace API allows value replacement on multiple records at once. Mass Search And Replace Document

HTTP Method - POST
URL - https://www.ragic.com/< account >/< tab folder >/< sheet index >/massOperation/massSearchReplace?api

{
"action": [
{
"field": < Field ID >,
"valueReplaced": < Value To Be Replaced >,
"valueNew": < Value To Replace With >,
}
]
}

==========

Response
{
"taskId": "6dbc796a-07d5-475b-b578-d254eb30f7d2"
}

Mass operations are asynchronous operations. The task Id of the operation can be used to monitor its progress.

HTTP Method - GET
URL - https://www.ragic.com/< account >?api&taskId=< task ID >

==========

Response
{
  "id": "6dbc796a-07d5-475b-b578-d254eb30f7d2",
  "ap": "myaccount",
  "taskName": "Mass Update",
  "status": "PROCESSING",
  "processed": 50,
  "success": 48,
  "fail": 2,
  "message": ""
}

The status field can be NOT_STARTED, PROCESSING, or DONE. The processed, success, and fail fields indicate the number of records handled so far.

Webhook is a way for your external application to subscribe to changes to your Ragic application. By subscribing to the changes, whenever a change is made on Ragic, Ragic will call the Webhook URL you provided to notify you of the change, including the ID of exact record that has been changed. The biggest advantage of using a webhook API instead of a RESTful API, is that it is a lot more efficient in processing changes. You no longer have to poll the API every X hours to watch for latest changes.

You can find webhook for a sheet on Ragic by clicking on the Tools button at the top. You will find the webhook in the Sync section. Things to note on the webhook API:

1. It will be triggered on create, update, and delete.
2. It is not completely synchronized, there may be a slight delay when the loading is high.
3. Changes will not include changes on related sheets like multiple versions.

Click on the “webhook” feature and enter the URL that should receive this notification, and you’re done. You can also opt in to receive full information on the modified data by checking the checkbox "send full content on changed record". To cancel the webhook configuration, click on the x in the corner of the webhook configuration box. The JSON format without full content would look like

[1 ,2 ,4]

For this example, it means entries with node ID 1 & 2 & 4 were changed. The JSON format with full content would look like

{
  "data": [
          < THE MODIFIED DATA ENTRY IN JSON >
   ]
  "apname": "< ACCOUNT NAME >",
  "path": "< PATH NAME >",
  "sheetIndex": < SHEET INDEX >,
  "eventType": "< EVENT TYPE CREATE/UPDATE/DELETE >"
}

You can also choose the types of events you want to trigger the webhook. We provide the following options: Trigger on new entry , Trigger on entry update , Trigger on entry deletion. Example of Trigger on new entry :

1. Create a record on the form page
2. Add a record on the list page

(Note: since other unmodified records are also saved here, this will generate a large number of Trigger on entry update)

1. Restore a record deleted
2. Mass create
3. Import

Example of Trigger on entry update :

1. Edit a record on the form page
2. Edit a record on the list page

(Note: since other unmodified records are also saved here, this will generate a large number of Event: update)

1. Mass update
2. Find & Replace
3. Import

Example of Trigger on entry deletion :

1. Delete a record on the form page
2. Delete a record on the list page

To ensure that the Webhook request truly comes from Ragic and that its content has not been tampered with, Webhooks configured as "Send full content of changed record." will include a signature in the request. After receiving the Webhook, you can use the public key we provide to verify the signature. If verification fails, it means the request may have been tampered with, and it is recommended to reject processing.

1. Obtain string-to-sign

1.1. Extract the data property from the Webhook request. (The data property should be in JSONArray format) 1.2. Serialize it into a JSON string with keys sorted alphabetically , no indentation , and no line breaks. In other words, "for each object in the JSONArray, reorder all fields alphabetically, then output as a single-line JSON".

// Before conversion (original data property):
[
  {
    "1001030":"banana",
    "1001029":"apple"
  }
]

// After conversion (string-to-sign):
[{"1001029":"apple","1001030":"banana"}]

Note: If the serialization method is inconsistent with ours, the signature verification will fail.

2. Verify the signature

2.1. Extract the signature property from the Webhook request. 2.2. Download the public key (see "Get Public Key"). 2.3. Use a verification tool that supports SHA256withRSA.

1. Convert the string-to-sign into a UTF-8 byte array
2. Verify the signature using the public key and algorithm

2.4. If verification succeeds, it means the request is from Ragic and its content has not been tampered with.

We provide two ways for you to obtain the public key. Choose the one that best fits your use case:

1. Get the public key string directly by calling: https://www.ragic.com/api/http/getWebhookSignaturePublicKey.jsp?type=string
2. Click here to download the PEM file.

It is recommended to cache the public key on your server and only re-download it on startup.

• If you are using the Private Host version, or if "Send full content of changed record" is not enabled, the Webhook will not support signature verification.
  • Make sure your program handles JSON serialization consistently; otherwise, verification errors will occur.