API Upload Project Assets: Difference between revisions

From zFairs Contest Management
← Older edit

Trent (talk | contribs)

3 user groups
537 edits
Michael (talk | contribs)
303 edits
No edit summary
Remove username/password API auth; ApiKey only
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Upload Project Assets ==  
== Upload Project Assets ==
Upload project images/assets or paperwork files to an existing project.


=== Upload Project Image ===
=== Authentication ===
You can use our API to upload images to a project, so these can be viewed by your judges or in the showcase. To do this, you need to POST a message to your site. Below is an example of what needs to be posted.
All data API calls are <code>POST</code> (unless noted) with JSON body:
 
{| class="wikitable"
|-
! Field !! Required !! Description
|-
| <code>ApiKey</code> || Yes || Private API key for your site.
|-
| <code>FairId</code> || Yes || Fair GUID from the site URL (<code>f</code> query parameter).
|-
| <code>Body</code> || Depends || Request payload. Use <code>{}</code> when no body fields are needed.
|}
 
 
Calls must be run '''server-side''' — do not expose your API key in a browser.
 
=== Response envelope ===
Most endpoints return:
 
<pre>
{
  Success: true,
  Message: null,  // error text when Success is false
  Body: { ... }    // endpoint-specific payload
}
</pre>
 
 
=== Upload project image / asset ===
POST <code>/api/data/project/file</code>


<syntaxhighlight lang="JavaScript" line>
<syntaxhighlight lang="JavaScript" line>
fetch('/api/data/project/file', {
fetch('/api/data/project/file', {
     method:'POST',
     method:'POST',
     headers:{'Content-Type': 'application/json'},
     headers:{'Content-Type': 'application/json'},
     body: JSON.stringify({
     body: JSON.stringify({
             Username:'admin username',
             ApiKey:'<Private key>',
            Password: 'password',
             FairId: '9df61f13-474b-442f-ac1f-edca7348ef71',
             FairId: '9df61f13-474b-442f-ac1f-edca7348ef71', //This value can be found in your url it's the value of f
             Body: {
             Body: {
"ProjectKey":"32161f13-474b-442f-ac1f-edca7348e000",
ProjectKey: "32161f13-474b-442f-ac1f-edca7348e000",
"Base64String" : "iVBORw0KGgoAAAANSUhEUgAAAQIAA...", //not required if you use DownloadFromUrl
Base64String: "iVBORw0KGgoAAAANSUhEUgAAAQIAA...", // not required if DownloadFromUrl is set
"DownloadFromUrl":"http://yoursite.com/somefile.png", //optional can be used in stead of Base64String
DownloadFromUrl: "https://yoursite.com/somefile.png", // optional alternative to Base64String
"FileName": "myAwesomeFile.png",
FileName: "myAwesomeFile.png",
"Caption": "indescribable"
Caption: "indescribable"
}
}
         })
         })
Line 25: Line 53:
.then(data=>{console.log('Success: ',data);})
.then(data=>{console.log('Success: ',data);})
.catch((error)=>{console.log('Error: ', error);});
.catch((error)=>{console.log('Error: ', error);});
</syntaxhighlight>
</syntaxhighlight>


=== Upload Project Paperwork  ===  
=== Upload project paperwork ===
You can use our API to upload project paperwork, so these can be viewed by your judges, SRC, and IRB. These files need to be PDFs. You will need to get the PaperworkFileType form the [[API Get Info]]. To do this, you need to POST a message to your site. Below is an example of what needs to be posted.
Same endpoint. Paperwork should be PDF. Set <code>PaperworkFileType</code> from [[API Get Info]] → <code>PaperworkFileTypes</code>.


<syntaxhighlight lang="JavaScript" line>
<syntaxhighlight lang="JavaScript" line>
fetch('/api/data/project/file', {
fetch('/api/data/project/file', {
     method:'POST',
     method:'POST',
     headers:{'Content-Type': 'application/json'},
     headers:{'Content-Type': 'application/json'},
     body: JSON.stringify({
     body: JSON.stringify({
             Username:'admin username',
             ApiKey:'<Private key>',
            Password: 'password',
             FairId: '9df61f13-474b-442f-ac1f-edca7348ef71',
             FairId: '9df61f13-474b-442f-ac1f-edca7348ef71', //This value can be found in your url it's the value of f
             Body: {
             Body: {
"ProjectKey":"32161f13-474b-442f-ac1f-edca7348e000",
ProjectKey: "32161f13-474b-442f-ac1f-edca7348e000",
"PaperworkFileType": 123, // this is pulled from the get info api
PaperworkFileType: 123,
"Base64String" : "iVBORw0KGgoAAAANSUhEUgAAAQIAA...", //not required if you use DownloadFromUrl
Base64String: "JVBERi0xLjQK...",
"DownloadFromUrl":"http://yoursite.com/somefile.png", //optional can be used in stead of Base64String
DownloadFromUrl: null,
"FileName": "myAwesomeFile.png"
FileName: "form1c.pdf",
Caption: "Form 1C"
}
}
         })
         })
Line 52: Line 78:
.then(data=>{console.log('Success: ',data);})
.then(data=>{console.log('Success: ',data);})
.catch((error)=>{console.log('Error: ', error);});
.catch((error)=>{console.log('Error: ', error);});
</syntaxhighlight>


</syntaxhighlight>
=== Response ===
<pre>
{
  Success: true,
  Message: null,
  Body: { ProjectKey: "...", FileName: "myAwesomeFile.png", ... }
}
</pre>
 
If the project key is invalid:
 
<pre>
{ Success: false, Message: "Project not found with ProjectKey: ..." }
</pre>


=== Field notes ===
* Provide '''either''' <code>Base64String</code> '''or''' <code>DownloadFromUrl</code>.
* When <code>PaperworkFileType</code> &gt; 0, the file is stored as paperwork; otherwise as a project asset/image.
* Uploaded files appear on [[API Get Projects]] under <code>projectFiles</code> / <code>paperworkFiles</code> with a <code>/file/showfile/{publicId}</code> path.


=== Related APIs ===
* [[API Get Projects]]
* [[API Get Info]]
* [[API Add Project]] / [[API Update Project]]


<br/><br/><br/><br/>
<br/><br/>
[[Category: API]]
[[Category: API]]

Latest revision as of 11:55, 25 July 2026

Upload Project Assets

Upload project images/assets or paperwork files to an existing project.

Authentication

All data API calls are POST (unless noted) with JSON body:

Field Required Description
ApiKey Yes Private API key for your site.
FairId Yes Fair GUID from the site URL (f query parameter).
Body Depends Request payload. Use {} when no body fields are needed.


Calls must be run server-side — do not expose your API key in a browser.

Response envelope

Most endpoints return: 

{
  Success: true,
  Message: null,   // error text when Success is false
  Body: { ... }    // endpoint-specific payload
}


Upload project image / asset

POST /api/data/project/file 

fetch('/api/data/project/file', {
    method:'POST',
    headers:{'Content-Type': 'application/json'},
    body: JSON.stringify({
            ApiKey:'<Private key>',
            FairId: '9df61f13-474b-442f-ac1f-edca7348ef71',
            Body: {
				ProjectKey: "32161f13-474b-442f-ac1f-edca7348e000",
				Base64String: "iVBORw0KGgoAAAANSUhEUgAAAQIAA...", // not required if DownloadFromUrl is set
				DownloadFromUrl: "https://yoursite.com/somefile.png", // optional alternative to Base64String
				FileName: "myAwesomeFile.png",
				Caption: "indescribable"
			}
        })
})
.then(response => response.json())
.then(data=>{console.log('Success: ',data);})
.catch((error)=>{console.log('Error: ', error);});

Upload project paperwork

Same endpoint. Paperwork should be PDF. Set PaperworkFileType from API Get Info → PaperworkFileTypes. 

fetch('/api/data/project/file', {
    method:'POST',
    headers:{'Content-Type': 'application/json'},
    body: JSON.stringify({
            ApiKey:'<Private key>',
            FairId: '9df61f13-474b-442f-ac1f-edca7348ef71',
            Body: {
				ProjectKey: "32161f13-474b-442f-ac1f-edca7348e000",
				PaperworkFileType: 123,
				Base64String: "JVBERi0xLjQK...",
				DownloadFromUrl: null,
				FileName: "form1c.pdf",
				Caption: "Form 1C"
			}
        })
})
.then(response => response.json())
.then(data=>{console.log('Success: ',data);})
.catch((error)=>{console.log('Error: ', error);});

Response

{
  Success: true,
  Message: null,
  Body: { ProjectKey: "...", FileName: "myAwesomeFile.png", ... }
}

If the project key is invalid: 

{ Success: false, Message: "Project not found with ProjectKey: ..." }

Field notes

  • Provide either Base64String or DownloadFromUrl.
  • When PaperworkFileType > 0, the file is stored as paperwork; otherwise as a project asset/image.
  • Uploaded files appear on API Get Projects under projectFiles / paperworkFiles with a /file/showfile/{publicId} path.



Retrieved from "https://wiki.zFairs.com/index.php?title=API_Upload_Project_Assets&oldid=970"